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
- accountType
- Type
- nullable string
- Description
The type of account on the donor service provider. This field is only used for portings in Ireland and may be
nullotherwise.Example:"prepaidUnregistered"Allowed values:postpaidMultipostpaidSingleprepaidRegisteredprepaidUnregistered
- Name
- address
- Type
- nullable object
- Description
- The address of the account holder on the donor service provider.
- Name
- behavior
- Type
- string
- Description
The behavior of the porting.
A value of
portInindicates that this porting will transfer the phone number from the previous provider.A porting with behavior
cancelOnlywill 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:cancelOnlyportIn
- Name
- billingPinExists
- Type
- boolean
- Description
Whether the billing PIN has been provided.
Example:true
- Name
- birthday
- Type
- nullable string
- Description
The birthday of the account holder on the donor service provider.
Example:"2017-07-21"
- Name
- canceledAt
- Type
- nullable string
- Description
Time when the porting was canceled.
Example:"2021-01-21T19:39:53Z"
- Name
- completedAt
- Type
- nullable string
- Description
Time when the porting was completed.
Example:"2021-01-21T19:36:57Z"
- Name
- createdAt
- Type
- string
- Description
Time when the porting was created.
Example:"2021-01-21T19:12:28Z"
- Name
- declinedAttempts
- Type
- integer
- Description
The number of declined porting attempts so far.
Example:0>= 0
- Name
- declinedCode
- Type
- nullable string
- Description
The code reason for the declined porting.
Example:"portingPhoneNumberPortProtected"
- Name
- declinedMessage
- Type
- nullable string
- Description
The reason description for the declined porting.
Example:"The phone number has port protection on the provider."
- Name
- donorProvider
- Type
- nullable ServiceProvider
- Description
- The service provider from whom the number is ported.
- Name
- donorProviderApproval
- Type
- nullable boolean
- Description
Whether the donor provider has approved or not the porting.
Example:true
- Name
- expiredAt
- Type
- nullable string
- Description
Time when the porting was expired.
Example:"2021-01-21T19:39:53Z"
- Name
- failedAt
- Type
- nullable string
- Description
Time when the porting was failed.
Example:"2021-01-21T19:39:53Z"
- Name
- failureReason
- Type
- nullable string
- Description
The reason for the porting failure. Only recorded when the porting failed because user consent could not be obtained.
Example:"consentNotGiven"Allowed values:consentCodeAttemptsExceededconsentNotGivenconsentRequestCanceled
- Name
- firstName
- Type
- nullable string
- Description
The first name of the account holder on the donor service provider.
Example:"Jerry"
- Name
- lastDeclinedAt
- Type
- nullable string
- Description
Time when the porting was last declined.
Example:"2021-01-21T19:31:13Z"
- Name
- lastName
- Type
- nullable string
- Description
The last name of the account holder on the donor service provider.
Example:"Seinfeld"
- Name
- lastRequestedAt
- Type
- nullable string
- Description
Time when the porting was last requested.
Example:"2021-01-21T19:22:31Z"
- Name
- phoneNumber
- Type
- string
- Description
The phone number to port in E.164 string_format.
Example:"+19591234567"
- Name
- provider
- Type
- string
- Description
The ID of the recipient network provider.
Example:"p9"
- Name
- recipientProvider
- Type
- ServiceProvider
- Description
- The service provider to whom the number is ported.
- Name
- requestBehavior
- Type
- string
- Status
- PREVIEW
- Description
Controls when the porting is submitted to the recipient network provider.
When
automatic, the porting is requested automatically as soon as all required information is present.When
manual, that automatic submission is withheld until the porting is requested explicitly via the request a porting endpoint. Amanualporting that has all required information waits in theinformationRequiredstatus, or indeclinedif it was declined, until it is requested.Example:"automatic"Allowed values:automaticmanual
- Name
- required
- Type
- array
- Description
List of fields required for the porting to be processable. The fields depend on the donor and recipient providers.
Example:["accountNumber","accountPin","accountType","address","birthday","donorProvider","donorProviderApproval","firstName","lastName"]
- Name
- scheduledOn
- Type
- nullable string
- Description
Date when the porting is scheduled to take effect.
For most providers this returns the provider-confirmed date when available, otherwise the user-requested date. For Concierge scheduled porting (p18), this returns the user-facing expected completion date and does not reflect the internal batch run date.
Scheduling a port-in is only supported in France, Ireland, Sweden and the United Kingdom. For other regions this reflects the provider-confirmed date when available or
nullotherwise.Example:"2021-01-21"
- Name
- status
- Type
- string
- Description
The current status of the porting.
Allowed values:draftinitiatedpendinginformationRequiredrequesteddeclinedcompletedcanceledexpiredfailed
- 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"
Porting object
{
"object": "porting",
"id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS",
"accountNumber": "123456789",
"accountPinExists": true,
"accountType": "prepaidUnregistered",
"address": {
"city": "New York City",
"country": "US",
"line1": "129 West 81st Street",
"line2": "Apartment 5",
"postalCode": "10024",
"state": "NY"
},
"behavior": "portIn",
"billingPinExists": true,
"birthday": "2017-07-21",
"canceledAt": "2021-01-21T19:39:53Z",
"completedAt": "2021-01-21T19:36:57Z",
"createdAt": "2021-01-21T19:12:28.0Z",
"declinedAttempts": 0,
"declinedCode": "portingPhoneNumberPortProtected",
"declinedMessage": "The phone number has port protection on the provider.",
"donorProvider": {
"object": "serviceProvider",
"id": "svp_0SNlurA01K6GY5L0XJffY8",
"country": "US",
"name": "AT&T",
"recipientProviders": [
{
"0": "p",
"1": "3"
}
]
},
"donorProviderApproval": true,
"expiredAt": "2021-01-21T19:39:53Z",
"failedAt": "2021-01-21T19:39:53Z",
"failureReason": "consentNotGiven",
"firstName": "Jerry",
"lastDeclinedAt": "2021-01-21T19:31:13Z",
"lastName": "Seinfeld",
"lastRequestedAt": "2021-01-21T19:22:31Z",
"phoneNumber": "+19591234567",
"provider": "p9",
"recipientProvider": {
"object": "serviceProvider",
"id": "svp_0SNlurA01K6GY5L0XJffY8",
"country": "US",
"name": "AT&T",
"recipientProviders": [
"p3"
]
},
"requestBehavior": "automatic",
"required": [
"accountNumber",
"accountPin",
"accountType",
"address",
"birthday",
"donorProvider",
"donorProviderApproval",
"firstName",
"lastName"
],
"scheduledOn": "2021-01-21",
"status": "draft",
"subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
"user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
}
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
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
- user
- Type
- string
- Description
The unique identifier of the user to be filtered by.
Example:"usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
- Name
- after
- Type
- string
- Description
A cursor for use in pagination. The
afterparameter 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
beforeparameter 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.
Example:20Default: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
afterpagination 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
beforepagination parameter if more items are available sorted before the current batch of items.
Request
curl https://api.gigs.com/projects/${GIGS_PROJECT}/portings \
-X GET \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${GIGS_TOKEN}" \
-H "Accept: application/json"
Responses 200
{
"object": "list",
"items": [
{
"object": "porting",
"id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS",
"accountNumber": "123456789",
"accountPinExists": true,
"accountType": "prepaidUnregistered",
"address": {
"city": "New York City",
"country": "US",
"line1": "129 West 81st Street",
"line2": "Apartment 5",
"postalCode": "10024",
"state": "NY"
},
"behavior": "portIn",
"billingPinExists": true,
"birthday": "2017-07-21",
"canceledAt": "2021-01-21T19:39:53Z",
"completedAt": "2021-01-21T19:36:57Z",
"createdAt": "2021-01-21T19:12:28Z",
"declinedAttempts": 0,
"declinedCode": "portingPhoneNumberPortProtected",
"declinedMessage": "The phone number has port protection on the provider.",
"donorProvider": {
"object": "serviceProvider",
"id": "svp_0SNlurA01K6GY5L0XJffY8",
"country": "US",
"name": "AT&T",
"recipientProviders": [
"p3"
]
},
"donorProviderApproval": true,
"expiredAt": "2021-01-21T19:39:53Z",
"failedAt": "2021-01-21T19:39:53Z",
"failureReason": "consentNotGiven",
"firstName": "Jerry",
"lastDeclinedAt": "2021-01-21T19:31:13Z",
"lastName": "Seinfeld",
"lastRequestedAt": "2021-01-21T19:22:31Z",
"phoneNumber": "+19591234567",
"provider": "p9",
"recipientProvider": {
"object": "serviceProvider",
"id": "svp_0SNlurA01K6GY5L0XJffY8",
"country": "US",
"name": "AT&T",
"recipientProviders": [
"p3"
]
},
"requestBehavior": "automatic",
"required": [
"accountNumber",
"accountPin",
"accountType",
"address",
"birthday",
"donorProvider",
"donorProviderApproval",
"firstName",
"lastName"
],
"scheduledOn": "2021-01-21",
"status": "draft",
"subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
"user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
}
],
"moreItemsAfter": null,
"moreItemsBefore": null
}
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 until all required information has been collected.
For a porting with a requestBehavior of automatic, the porting will then be requested. For a porting with a requestBehavior of manual, it stays in informationRequired until it is requested via the request a porting endpoint.
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
- accountType
- Type
- nullable string
- Description
The type of account on the donor service provider. Required for portings in Ireland.
Example:"prepaidUnregistered"Allowed values:postpaidMultipostpaidSingleprepaidRegisteredprepaidUnregistered
- 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
portInto transfer the phone number from the previous provider.Use
cancelOnlyto cancel the previous service without transferring the number. This behavior is currently only available for local plans in the United Kingdom.Defaults to
portInif no value is provided.Example:"portIn"Default:portInAllowed values:cancelOnlyportIn
- Name
- billingPin
- Type
- nullable string
- Status
- PREVIEW
- Description
The billing pin for the account on the donor service provider. This will be used only for the porting.
Example:"1234"
- 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
- Description
The phone number to port in E.164 string_format.
Example:"+19591234567"
required- Name
- provider
- Type
- string
- Description
The name of the receiving network provider.
Example:"p9"
required- Name
- requestBehavior
- Type
- nullable string
- Status
- PREVIEW
- Description
Controls when the porting is submitted to the recipient network provider.
Use
automaticto have the porting requested automatically as soon as all required information is present.Use
manualto withhold that automatic submission, for example to give a user a chance to review the porting first. The porting must then be requested explicitly, once ready, via the request a porting endpoint. Amanualporting that has all required information waits in theinformationRequiredstatus, or indeclinedif it was declined, until it is requested.Defaults to
automaticif no value is provided.Example:"automatic"Default:automaticAllowed values:automaticmanual
- Name
- scheduledOn
- Type
- nullable string
- Status
- PREVIEW
- Description
The date that the porting is scheduled to take effect.
Scheduling is only supported by providers in France, Ireland, Sweden and the United Kingdom. Attempting to schedule a porting for any other provider will result in an error. Providers may also apply restrictions to the date.
Use
nullto 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 requested from the provider, the scheduled date has already passed, then the porting will instead occur as soon as possible.
Example:"2021-01-21"
Path Parameters
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
- accountType
- Type
- nullable string
- Description
The type of account on the donor service provider. This field is only used for portings in Ireland and may be
nullotherwise.Example:"prepaidUnregistered"Allowed values:postpaidMultipostpaidSingleprepaidRegisteredprepaidUnregistered
- Name
- address
- Type
- nullable object
- Description
- The address of the account holder on the donor service provider.
- Name
- behavior
- Type
- string
- Description
The behavior of the porting.
A value of
portInindicates that this porting will transfer the phone number from the previous provider.A porting with behavior
cancelOnlywill 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:cancelOnlyportIn
- Name
- billingPinExists
- Type
- boolean
- Description
Whether the billing PIN has been provided.
Example:true
- Name
- birthday
- Type
- nullable string
- Description
The birthday of the account holder on the donor service provider.
Example:"2017-07-21"
- Name
- canceledAt
- Type
- nullable string
- Description
Time when the porting was canceled.
Example:"2021-01-21T19:39:53Z"
- Name
- completedAt
- Type
- nullable string
- Description
Time when the porting was completed.
Example:"2021-01-21T19:36:57Z"
- Name
- createdAt
- Type
- string
- Description
Time when the porting was created.
Example:"2021-01-21T19:12:28Z"
- Name
- declinedAttempts
- Type
- integer
- Description
The number of declined porting attempts so far.
Example:0>= 0
- Name
- declinedCode
- Type
- nullable string
- Description
The code reason for the declined porting.
Example:"portingPhoneNumberPortProtected"
- Name
- declinedMessage
- Type
- nullable string
- Description
The reason description for the declined porting.
Example:"The phone number has port protection on the provider."
- Name
- donorProvider
- Type
- nullable ServiceProvider
- Description
- The service provider from whom the number is ported.
- Name
- donorProviderApproval
- Type
- nullable boolean
- Description
Whether the donor provider has approved or not the porting.
Example:true
- Name
- expiredAt
- Type
- nullable string
- Description
Time when the porting was expired.
Example:"2021-01-21T19:39:53Z"
- Name
- failedAt
- Type
- nullable string
- Description
Time when the porting was failed.
Example:"2021-01-21T19:39:53Z"
- Name
- failureReason
- Type
- nullable string
- Description
The reason for the porting failure. Only recorded when the porting failed because user consent could not be obtained.
Example:"consentNotGiven"Allowed values:consentCodeAttemptsExceededconsentNotGivenconsentRequestCanceled
- Name
- firstName
- Type
- nullable string
- Description
The first name of the account holder on the donor service provider.
Example:"Jerry"
- Name
- lastDeclinedAt
- Type
- nullable string
- Description
Time when the porting was last declined.
Example:"2021-01-21T19:31:13Z"
- Name
- lastName
- Type
- nullable string
- Description
The last name of the account holder on the donor service provider.
Example:"Seinfeld"
- Name
- lastRequestedAt
- Type
- nullable string
- Description
Time when the porting was last requested.
Example:"2021-01-21T19:22:31Z"
- Name
- phoneNumber
- Type
- string
- Description
The phone number to port in E.164 string_format.
Example:"+19591234567"
- Name
- provider
- Type
- string
- Description
The ID of the recipient network provider.
Example:"p9"
- Name
- recipientProvider
- Type
- ServiceProvider
- Description
- The service provider to whom the number is ported.
- Name
- requestBehavior
- Type
- string
- Status
- PREVIEW
- Description
Controls when the porting is submitted to the recipient network provider.
When
automatic, the porting is requested automatically as soon as all required information is present.When
manual, that automatic submission is withheld until the porting is requested explicitly via the request a porting endpoint. Amanualporting that has all required information waits in theinformationRequiredstatus, or indeclinedif it was declined, until it is requested.Example:"automatic"Allowed values:automaticmanual
- Name
- required
- Type
- array
- Description
List of fields required for the porting to be processable. The fields depend on the donor and recipient providers.
Example:["accountNumber","accountPin","accountType","address","birthday","donorProvider","donorProviderApproval","firstName","lastName"]
- Name
- scheduledOn
- Type
- nullable string
- Description
Date when the porting is scheduled to take effect.
For most providers this returns the provider-confirmed date when available, otherwise the user-requested date. For Concierge scheduled porting (p18), this returns the user-facing expected completion date and does not reflect the internal batch run date.
Scheduling a port-in is only supported in France, Ireland, Sweden and the United Kingdom. For other regions this reflects the provider-confirmed date when available or
nullotherwise.Example:"2021-01-21"
- Name
- status
- Type
- string
- Description
The current status of the porting.
Allowed values:draftinitiatedpendinginformationRequiredrequesteddeclinedcompletedcanceledexpiredfailed
- 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
curl https://api.gigs.com/projects/${GIGS_PROJECT}/portings \
-X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${GIGS_TOKEN}" \
-H "Accept: application/json" \
-d '{
"accountNumber": "123456789",
"accountPin": "1234",
"accountType": "prepaidUnregistered",
"address": {
"city": "New York City",
"country": "US",
"line1": "129 West 81st Street",
"line2": "Apartment 5",
"postalCode": "10024",
"state": "NY"
},
"behavior": "portIn",
"billingPin": "1234",
"birthday": "2017-07-21",
"donorProvider": "svp_0SNlurA01K6GY5L0XJffY8",
"donorProviderApproval": true,
"firstName": "Jerry",
"lastName": "Seinfeld",
"phoneNumber": "+19591234567",
"provider": "p9",
"requestBehavior": "automatic",
"scheduledOn": "2021-01-21",
"user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
}'
Response 201
{
"object": "porting",
"id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS",
"accountNumber": "123456789",
"accountPinExists": true,
"accountType": "prepaidUnregistered",
"address": {
"city": "New York City",
"country": "US",
"line1": "129 West 81st Street",
"line2": "Apartment 5",
"postalCode": "10024",
"state": "NY"
},
"behavior": "portIn",
"billingPinExists": true,
"birthday": "2017-07-21",
"canceledAt": "2021-01-21T19:39:53Z",
"completedAt": "2021-01-21T19:36:57Z",
"createdAt": "2021-01-21T19:12:28Z",
"declinedAttempts": 0,
"declinedCode": "portingPhoneNumberPortProtected",
"declinedMessage": "The phone number has port protection on the provider.",
"donorProvider": {
"object": "serviceProvider",
"id": "svp_0SNlurA01K6GY5L0XJffY8",
"country": "US",
"name": "AT&T",
"recipientProviders": [
"p3"
]
},
"donorProviderApproval": true,
"expiredAt": "2021-01-21T19:39:53Z",
"failedAt": "2021-01-21T19:39:53Z",
"failureReason": "consentNotGiven",
"firstName": "Jerry",
"lastDeclinedAt": "2021-01-21T19:31:13Z",
"lastName": "Seinfeld",
"lastRequestedAt": "2021-01-21T19:22:31Z",
"phoneNumber": "+19591234567",
"provider": "p9",
"recipientProvider": {
"object": "serviceProvider",
"id": "svp_0SNlurA01K6GY5L0XJffY8",
"country": "US",
"name": "AT&T",
"recipientProviders": [
"p3"
]
},
"requestBehavior": "automatic",
"required": [
"accountNumber",
"accountPin",
"accountType",
"address",
"birthday",
"donorProvider",
"donorProviderApproval",
"firstName",
"lastName"
],
"scheduledOn": "2021-01-21",
"status": "draft",
"subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
"user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
}
Retrieve a Porting
Retrieves the details of an existing porting.
Path Parameters
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
- accountType
- Type
- nullable string
- Description
The type of account on the donor service provider. This field is only used for portings in Ireland and may be
nullotherwise.Example:"prepaidUnregistered"Allowed values:postpaidMultipostpaidSingleprepaidRegisteredprepaidUnregistered
- Name
- address
- Type
- nullable object
- Description
- The address of the account holder on the donor service provider.
- Name
- behavior
- Type
- string
- Description
The behavior of the porting.
A value of
portInindicates that this porting will transfer the phone number from the previous provider.A porting with behavior
cancelOnlywill 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:cancelOnlyportIn
- Name
- billingPinExists
- Type
- boolean
- Description
Whether the billing PIN has been provided.
Example:true
- Name
- birthday
- Type
- nullable string
- Description
The birthday of the account holder on the donor service provider.
Example:"2017-07-21"
- Name
- canceledAt
- Type
- nullable string
- Description
Time when the porting was canceled.
Example:"2021-01-21T19:39:53Z"
- Name
- completedAt
- Type
- nullable string
- Description
Time when the porting was completed.
Example:"2021-01-21T19:36:57Z"
- Name
- createdAt
- Type
- string
- Description
Time when the porting was created.
Example:"2021-01-21T19:12:28Z"
- Name
- declinedAttempts
- Type
- integer
- Description
The number of declined porting attempts so far.
Example:0>= 0
- Name
- declinedCode
- Type
- nullable string
- Description
The code reason for the declined porting.
Example:"portingPhoneNumberPortProtected"
- Name
- declinedMessage
- Type
- nullable string
- Description
The reason description for the declined porting.
Example:"The phone number has port protection on the provider."
- Name
- donorProvider
- Type
- nullable ServiceProvider
- Description
- The service provider from whom the number is ported.
- Name
- donorProviderApproval
- Type
- nullable boolean
- Description
Whether the donor provider has approved or not the porting.
Example:true
- Name
- expiredAt
- Type
- nullable string
- Description
Time when the porting was expired.
Example:"2021-01-21T19:39:53Z"
- Name
- failedAt
- Type
- nullable string
- Description
Time when the porting was failed.
Example:"2021-01-21T19:39:53Z"
- Name
- failureReason
- Type
- nullable string
- Description
The reason for the porting failure. Only recorded when the porting failed because user consent could not be obtained.
Example:"consentNotGiven"Allowed values:consentCodeAttemptsExceededconsentNotGivenconsentRequestCanceled
- Name
- firstName
- Type
- nullable string
- Description
The first name of the account holder on the donor service provider.
Example:"Jerry"
- Name
- lastDeclinedAt
- Type
- nullable string
- Description
Time when the porting was last declined.
Example:"2021-01-21T19:31:13Z"
- Name
- lastName
- Type
- nullable string
- Description
The last name of the account holder on the donor service provider.
Example:"Seinfeld"
- Name
- lastRequestedAt
- Type
- nullable string
- Description
Time when the porting was last requested.
Example:"2021-01-21T19:22:31Z"
- Name
- phoneNumber
- Type
- string
- Description
The phone number to port in E.164 string_format.
Example:"+19591234567"
- Name
- provider
- Type
- string
- Description
The ID of the recipient network provider.
Example:"p9"
- Name
- recipientProvider
- Type
- ServiceProvider
- Description
- The service provider to whom the number is ported.
- Name
- requestBehavior
- Type
- string
- Status
- PREVIEW
- Description
Controls when the porting is submitted to the recipient network provider.
When
automatic, the porting is requested automatically as soon as all required information is present.When
manual, that automatic submission is withheld until the porting is requested explicitly via the request a porting endpoint. Amanualporting that has all required information waits in theinformationRequiredstatus, or indeclinedif it was declined, until it is requested.Example:"automatic"Allowed values:automaticmanual
- Name
- required
- Type
- array
- Description
List of fields required for the porting to be processable. The fields depend on the donor and recipient providers.
Example:["accountNumber","accountPin","accountType","address","birthday","donorProvider","donorProviderApproval","firstName","lastName"]
- Name
- scheduledOn
- Type
- nullable string
- Description
Date when the porting is scheduled to take effect.
For most providers this returns the provider-confirmed date when available, otherwise the user-requested date. For Concierge scheduled porting (p18), this returns the user-facing expected completion date and does not reflect the internal batch run date.
Scheduling a port-in is only supported in France, Ireland, Sweden and the United Kingdom. For other regions this reflects the provider-confirmed date when available or
nullotherwise.Example:"2021-01-21"
- Name
- status
- Type
- string
- Description
The current status of the porting.
Allowed values:draftinitiatedpendinginformationRequiredrequesteddeclinedcompletedcanceledexpiredfailed
- 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
curl https://api.gigs.com/projects/${GIGS_PROJECT}/portings/{porting} \
-X GET \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${GIGS_TOKEN}" \
-H "Accept: application/json"
Response 200
{
"object": "porting",
"id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS",
"accountNumber": "123456789",
"accountPinExists": true,
"accountType": "prepaidUnregistered",
"address": {
"city": "New York City",
"country": "US",
"line1": "129 West 81st Street",
"line2": "Apartment 5",
"postalCode": "10024",
"state": "NY"
},
"behavior": "portIn",
"billingPinExists": true,
"birthday": "2017-07-21",
"canceledAt": "2021-01-21T19:39:53Z",
"completedAt": "2021-01-21T19:36:57Z",
"createdAt": "2021-01-21T19:12:28Z",
"declinedAttempts": 0,
"declinedCode": "portingPhoneNumberPortProtected",
"declinedMessage": "The phone number has port protection on the provider.",
"donorProvider": {
"object": "serviceProvider",
"id": "svp_0SNlurA01K6GY5L0XJffY8",
"country": "US",
"name": "AT&T",
"recipientProviders": [
"p3"
]
},
"donorProviderApproval": true,
"expiredAt": "2021-01-21T19:39:53Z",
"failedAt": "2021-01-21T19:39:53Z",
"failureReason": "consentNotGiven",
"firstName": "Jerry",
"lastDeclinedAt": "2021-01-21T19:31:13Z",
"lastName": "Seinfeld",
"lastRequestedAt": "2021-01-21T19:22:31Z",
"phoneNumber": "+19591234567",
"provider": "p9",
"recipientProvider": {
"object": "serviceProvider",
"id": "svp_0SNlurA01K6GY5L0XJffY8",
"country": "US",
"name": "AT&T",
"recipientProviders": [
"p3"
]
},
"requestBehavior": "automatic",
"required": [
"accountNumber",
"accountPin",
"accountType",
"address",
"birthday",
"donorProvider",
"donorProviderApproval",
"firstName",
"lastName"
],
"scheduledOn": "2021-01-21",
"status": "draft",
"subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
"user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
}
Delete a draft porting
Deletes a porting that is in the draft state.
Path Parameters
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
- accountType
- Type
- nullable string
- Description
The type of account on the donor service provider. This field is only used for portings in Ireland and may be
nullotherwise.Example:"prepaidUnregistered"Allowed values:postpaidMultipostpaidSingleprepaidRegisteredprepaidUnregistered
- Name
- address
- Type
- nullable object
- Description
- The address of the account holder on the donor service provider.
- Name
- behavior
- Type
- string
- Description
The behavior of the porting.
A value of
portInindicates that this porting will transfer the phone number from the previous provider.A porting with behavior
cancelOnlywill 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:cancelOnlyportIn
- Name
- billingPinExists
- Type
- boolean
- Description
Whether the billing PIN has been provided.
Example:true
- Name
- birthday
- Type
- nullable string
- Description
The birthday of the account holder on the donor service provider.
Example:"2017-07-21"
- Name
- canceledAt
- Type
- nullable string
- Description
Time when the porting was canceled.
Example:"2021-01-21T19:39:53Z"
- Name
- completedAt
- Type
- nullable string
- Description
Time when the porting was completed.
Example:"2021-01-21T19:36:57Z"
- Name
- createdAt
- Type
- string
- Description
Time when the porting was created.
Example:"2021-01-21T19:12:28Z"
- Name
- declinedAttempts
- Type
- integer
- Description
The number of declined porting attempts so far.
Example:0>= 0
- Name
- declinedCode
- Type
- nullable string
- Description
The code reason for the declined porting.
Example:"portingPhoneNumberPortProtected"
- Name
- declinedMessage
- Type
- nullable string
- Description
The reason description for the declined porting.
Example:"The phone number has port protection on the provider."
- Name
- donorProvider
- Type
- nullable ServiceProvider
- Description
- The service provider from whom the number is ported.
- Name
- donorProviderApproval
- Type
- nullable boolean
- Description
Whether the donor provider has approved or not the porting.
Example:true
- Name
- expiredAt
- Type
- nullable string
- Description
Time when the porting was expired.
Example:"2021-01-21T19:39:53Z"
- Name
- failedAt
- Type
- nullable string
- Description
Time when the porting was failed.
Example:"2021-01-21T19:39:53Z"
- Name
- failureReason
- Type
- nullable string
- Description
The reason for the porting failure. Only recorded when the porting failed because user consent could not be obtained.
Example:"consentNotGiven"Allowed values:consentCodeAttemptsExceededconsentNotGivenconsentRequestCanceled
- Name
- firstName
- Type
- nullable string
- Description
The first name of the account holder on the donor service provider.
Example:"Jerry"
- Name
- lastDeclinedAt
- Type
- nullable string
- Description
Time when the porting was last declined.
Example:"2021-01-21T19:31:13Z"
- Name
- lastName
- Type
- nullable string
- Description
The last name of the account holder on the donor service provider.
Example:"Seinfeld"
- Name
- lastRequestedAt
- Type
- nullable string
- Description
Time when the porting was last requested.
Example:"2021-01-21T19:22:31Z"
- Name
- phoneNumber
- Type
- string
- Description
The phone number to port in E.164 string_format.
Example:"+19591234567"
- Name
- provider
- Type
- string
- Description
The ID of the recipient network provider.
Example:"p9"
- Name
- recipientProvider
- Type
- ServiceProvider
- Description
- The service provider to whom the number is ported.
- Name
- requestBehavior
- Type
- string
- Status
- PREVIEW
- Description
Controls when the porting is submitted to the recipient network provider.
When
automatic, the porting is requested automatically as soon as all required information is present.When
manual, that automatic submission is withheld until the porting is requested explicitly via the request a porting endpoint. Amanualporting that has all required information waits in theinformationRequiredstatus, or indeclinedif it was declined, until it is requested.Example:"automatic"Allowed values:automaticmanual
- Name
- required
- Type
- array
- Description
List of fields required for the porting to be processable. The fields depend on the donor and recipient providers.
Example:["accountNumber","accountPin","accountType","address","birthday","donorProvider","donorProviderApproval","firstName","lastName"]
- Name
- scheduledOn
- Type
- nullable string
- Description
Date when the porting is scheduled to take effect.
For most providers this returns the provider-confirmed date when available, otherwise the user-requested date. For Concierge scheduled porting (p18), this returns the user-facing expected completion date and does not reflect the internal batch run date.
Scheduling a port-in is only supported in France, Ireland, Sweden and the United Kingdom. For other regions this reflects the provider-confirmed date when available or
nullotherwise.Example:"2021-01-21"
- Name
- status
- Type
- string
- Description
The current status of the porting.
Allowed values:draftinitiatedpendinginformationRequiredrequesteddeclinedcompletedcanceledexpiredfailed
- 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
curl https://api.gigs.com/projects/${GIGS_PROJECT}/portings/{porting} \
-X DELETE \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${GIGS_TOKEN}" \
-H "Accept: application/json"
Response 200
{
"object": "porting",
"id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS",
"accountNumber": "123456789",
"accountPinExists": true,
"accountType": "prepaidUnregistered",
"address": {
"city": "New York City",
"country": "US",
"line1": "129 West 81st Street",
"line2": "Apartment 5",
"postalCode": "10024",
"state": "NY"
},
"behavior": "portIn",
"billingPinExists": true,
"birthday": "2017-07-21",
"canceledAt": "2021-01-21T19:39:53Z",
"completedAt": "2021-01-21T19:36:57Z",
"createdAt": "2021-01-21T19:12:28Z",
"declinedAttempts": 0,
"declinedCode": "portingPhoneNumberPortProtected",
"declinedMessage": "The phone number has port protection on the provider.",
"donorProvider": {
"object": "serviceProvider",
"id": "svp_0SNlurA01K6GY5L0XJffY8",
"country": "US",
"name": "AT&T",
"recipientProviders": [
"p3"
]
},
"donorProviderApproval": true,
"expiredAt": "2021-01-21T19:39:53Z",
"failedAt": "2021-01-21T19:39:53Z",
"failureReason": "consentNotGiven",
"firstName": "Jerry",
"lastDeclinedAt": "2021-01-21T19:31:13Z",
"lastName": "Seinfeld",
"lastRequestedAt": "2021-01-21T19:22:31Z",
"phoneNumber": "+19591234567",
"provider": "p9",
"recipientProvider": {
"object": "serviceProvider",
"id": "svp_0SNlurA01K6GY5L0XJffY8",
"country": "US",
"name": "AT&T",
"recipientProviders": [
"p3"
]
},
"requestBehavior": "automatic",
"required": [
"accountNumber",
"accountPin",
"accountType",
"address",
"birthday",
"donorProvider",
"donorProviderApproval",
"firstName",
"lastName"
],
"scheduledOn": "2021-01-21",
"status": "draft",
"subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
"user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
}
Update a porting
Updates a porting with the given parameters.
Depending on the status of the porting, some fields may not be updated anymore.
For a porting with a requestBehavior of automatic, the porting will be requested when all the required information is provided. 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.
For a porting with a requestBehavior of manual, the porting is only requested via the request a porting endpoint, including when it was declined.
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
- accountType
- Type
- string
- Description
The type of account on the donor service provider. Required for portings in Ireland.
Example:"prepaidUnregistered"Allowed values:postpaidMultipostpaidSingleprepaidRegisteredprepaidUnregistered
- 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
portInto transfer the phone number from the previous provider.Use
cancelOnlyto 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:cancelOnlyportIn
- Name
- billingPin
- Type
- string
- Status
- PREVIEW
- Description
The billing pin for the account on the donor service provider. This will be used only for the porting.
Example:"1234"
- 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 string_format. This is only updatable when the porting is in a status of: draft, or, for providers
p11andp12, declined or informationRequired.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
- requestBehavior
- Type
- string
- Status
- PREVIEW
- Description
Controls when the porting is submitted to the recipient network provider.
Use
automaticto have the porting requested automatically as soon as all required information is present.Use
manualto withhold that automatic submission, for example to give a user a chance to review the porting first. The porting must then be requested explicitly, once ready, via the request a porting endpoint. Amanualporting that has all required information waits in theinformationRequiredstatus, or indeclinedif it was declined, until it is requested.Example:"automatic"Allowed values:automaticmanual
- Name
- scheduledOn
- Type
- nullable string
- Status
- PREVIEW
- Description
Date when the porting is scheduled to take effect.
Scheduling is only supported by providers in France, Ireland, Sweden and the United Kingdom. Attempting to schedule a porting for any other provider will result in an error. Providers may also apply restrictions to the date.
Use
nullto 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
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
- accountType
- Type
- nullable string
- Description
The type of account on the donor service provider. This field is only used for portings in Ireland and may be
nullotherwise.Example:"prepaidUnregistered"Allowed values:postpaidMultipostpaidSingleprepaidRegisteredprepaidUnregistered
- Name
- address
- Type
- nullable object
- Description
- The address of the account holder on the donor service provider.
- Name
- behavior
- Type
- string
- Description
The behavior of the porting.
A value of
portInindicates that this porting will transfer the phone number from the previous provider.A porting with behavior
cancelOnlywill 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:cancelOnlyportIn
- Name
- billingPinExists
- Type
- boolean
- Description
Whether the billing PIN has been provided.
Example:true
- Name
- birthday
- Type
- nullable string
- Description
The birthday of the account holder on the donor service provider.
Example:"2017-07-21"
- Name
- canceledAt
- Type
- nullable string
- Description
Time when the porting was canceled.
Example:"2021-01-21T19:39:53Z"
- Name
- completedAt
- Type
- nullable string
- Description
Time when the porting was completed.
Example:"2021-01-21T19:36:57Z"
- Name
- createdAt
- Type
- string
- Description
Time when the porting was created.
Example:"2021-01-21T19:12:28Z"
- Name
- declinedAttempts
- Type
- integer
- Description
The number of declined porting attempts so far.
Example:0>= 0
- Name
- declinedCode
- Type
- nullable string
- Description
The code reason for the declined porting.
Example:"portingPhoneNumberPortProtected"
- Name
- declinedMessage
- Type
- nullable string
- Description
The reason description for the declined porting.
Example:"The phone number has port protection on the provider."
- Name
- donorProvider
- Type
- nullable ServiceProvider
- Description
- The service provider from whom the number is ported.
- Name
- donorProviderApproval
- Type
- nullable boolean
- Description
Whether the donor provider has approved or not the porting.
Example:true
- Name
- expiredAt
- Type
- nullable string
- Description
Time when the porting was expired.
Example:"2021-01-21T19:39:53Z"
- Name
- failedAt
- Type
- nullable string
- Description
Time when the porting was failed.
Example:"2021-01-21T19:39:53Z"
- Name
- failureReason
- Type
- nullable string
- Description
The reason for the porting failure. Only recorded when the porting failed because user consent could not be obtained.
Example:"consentNotGiven"Allowed values:consentCodeAttemptsExceededconsentNotGivenconsentRequestCanceled
- Name
- firstName
- Type
- nullable string
- Description
The first name of the account holder on the donor service provider.
Example:"Jerry"
- Name
- lastDeclinedAt
- Type
- nullable string
- Description
Time when the porting was last declined.
Example:"2021-01-21T19:31:13Z"
- Name
- lastName
- Type
- nullable string
- Description
The last name of the account holder on the donor service provider.
Example:"Seinfeld"
- Name
- lastRequestedAt
- Type
- nullable string
- Description
Time when the porting was last requested.
Example:"2021-01-21T19:22:31Z"
- Name
- phoneNumber
- Type
- string
- Description
The phone number to port in E.164 string_format.
Example:"+19591234567"
- Name
- provider
- Type
- string
- Description
The ID of the recipient network provider.
Example:"p9"
- Name
- recipientProvider
- Type
- ServiceProvider
- Description
- The service provider to whom the number is ported.
- Name
- requestBehavior
- Type
- string
- Status
- PREVIEW
- Description
Controls when the porting is submitted to the recipient network provider.
When
automatic, the porting is requested automatically as soon as all required information is present.When
manual, that automatic submission is withheld until the porting is requested explicitly via the request a porting endpoint. Amanualporting that has all required information waits in theinformationRequiredstatus, or indeclinedif it was declined, until it is requested.Example:"automatic"Allowed values:automaticmanual
- Name
- required
- Type
- array
- Description
List of fields required for the porting to be processable. The fields depend on the donor and recipient providers.
Example:["accountNumber","accountPin","accountType","address","birthday","donorProvider","donorProviderApproval","firstName","lastName"]
- Name
- scheduledOn
- Type
- nullable string
- Description
Date when the porting is scheduled to take effect.
For most providers this returns the provider-confirmed date when available, otherwise the user-requested date. For Concierge scheduled porting (p18), this returns the user-facing expected completion date and does not reflect the internal batch run date.
Scheduling a port-in is only supported in France, Ireland, Sweden and the United Kingdom. For other regions this reflects the provider-confirmed date when available or
nullotherwise.Example:"2021-01-21"
- Name
- status
- Type
- string
- Description
The current status of the porting.
Allowed values:draftinitiatedpendinginformationRequiredrequesteddeclinedcompletedcanceledexpiredfailed
- 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
curl https://api.gigs.com/projects/${GIGS_PROJECT}/portings/{porting} \
-X PATCH \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${GIGS_TOKEN}" \
-H "Accept: application/json" \
-d '{
"accountNumber": "123456789",
"accountPin": "1234",
"accountType": "prepaidUnregistered",
"address": {
"city": "New York City",
"country": "US",
"line1": "129 West 81st Street",
"line2": "Apartment 5",
"postalCode": "10024",
"state": "NY"
},
"behavior": "portIn",
"billingPin": "1234",
"birthday": "2017-07-21",
"donorProvider": "svp_0SNlurA01K6GY5L0XJffY8",
"donorProviderApproval": true,
"firstName": "Jerry",
"lastName": "Seinfeld",
"phoneNumber": "+19591234567",
"provider": "p9",
"requestBehavior": "automatic",
"scheduledOn": "2021-01-21"
}'
Response 200
{
"object": "porting",
"id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS",
"accountNumber": "123456789",
"accountPinExists": true,
"accountType": "prepaidUnregistered",
"address": {
"city": "New York City",
"country": "US",
"line1": "129 West 81st Street",
"line2": "Apartment 5",
"postalCode": "10024",
"state": "NY"
},
"behavior": "portIn",
"billingPinExists": true,
"birthday": "2017-07-21",
"canceledAt": "2021-01-21T19:39:53Z",
"completedAt": "2021-01-21T19:36:57Z",
"createdAt": "2021-01-21T19:12:28Z",
"declinedAttempts": 0,
"declinedCode": "portingPhoneNumberPortProtected",
"declinedMessage": "The phone number has port protection on the provider.",
"donorProvider": {
"object": "serviceProvider",
"id": "svp_0SNlurA01K6GY5L0XJffY8",
"country": "US",
"name": "AT&T",
"recipientProviders": [
"p3"
]
},
"donorProviderApproval": true,
"expiredAt": "2021-01-21T19:39:53Z",
"failedAt": "2021-01-21T19:39:53Z",
"failureReason": "consentNotGiven",
"firstName": "Jerry",
"lastDeclinedAt": "2021-01-21T19:31:13Z",
"lastName": "Seinfeld",
"lastRequestedAt": "2021-01-21T19:22:31Z",
"phoneNumber": "+19591234567",
"provider": "p9",
"recipientProvider": {
"object": "serviceProvider",
"id": "svp_0SNlurA01K6GY5L0XJffY8",
"country": "US",
"name": "AT&T",
"recipientProviders": [
"p3"
]
},
"requestBehavior": "automatic",
"required": [
"accountNumber",
"accountPin",
"accountType",
"address",
"birthday",
"donorProvider",
"donorProviderApproval",
"firstName",
"lastName"
],
"scheduledOn": "2021-01-21",
"status": "draft",
"subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
"user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
}
Cancel a porting
Cancels a porting. A porting can be cancelled in the following situations:
- it is in the
initiated,declinedorinformationRequiredstate, - it is in the
pendingstate and the porting request has not been sent to the provider yet, - it is in the
requestedstate and it is scheduled for a future date that is within the provider's cancellation window.
Canceling a porting will result in the activation of the subscription with a new number. To cancel the whole process, end the subscription instead.
Path Parameters
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
- accountType
- Type
- nullable string
- Description
The type of account on the donor service provider. This field is only used for portings in Ireland and may be
nullotherwise.Example:"prepaidUnregistered"Allowed values:postpaidMultipostpaidSingleprepaidRegisteredprepaidUnregistered
- Name
- address
- Type
- nullable object
- Description
- The address of the account holder on the donor service provider.
- Name
- behavior
- Type
- string
- Description
The behavior of the porting.
A value of
portInindicates that this porting will transfer the phone number from the previous provider.A porting with behavior
cancelOnlywill 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:cancelOnlyportIn
- Name
- billingPinExists
- Type
- boolean
- Description
Whether the billing PIN has been provided.
Example:true
- Name
- birthday
- Type
- nullable string
- Description
The birthday of the account holder on the donor service provider.
Example:"2017-07-21"
- Name
- canceledAt
- Type
- nullable string
- Description
Time when the porting was canceled.
Example:"2021-01-21T19:39:53Z"
- Name
- completedAt
- Type
- nullable string
- Description
Time when the porting was completed.
Example:"2021-01-21T19:36:57Z"
- Name
- createdAt
- Type
- string
- Description
Time when the porting was created.
Example:"2021-01-21T19:12:28Z"
- Name
- declinedAttempts
- Type
- integer
- Description
The number of declined porting attempts so far.
Example:0>= 0
- Name
- declinedCode
- Type
- nullable string
- Description
The code reason for the declined porting.
Example:"portingPhoneNumberPortProtected"
- Name
- declinedMessage
- Type
- nullable string
- Description
The reason description for the declined porting.
Example:"The phone number has port protection on the provider."
- Name
- donorProvider
- Type
- nullable ServiceProvider
- Description
- The service provider from whom the number is ported.
- Name
- donorProviderApproval
- Type
- nullable boolean
- Description
Whether the donor provider has approved or not the porting.
Example:true
- Name
- expiredAt
- Type
- nullable string
- Description
Time when the porting was expired.
Example:"2021-01-21T19:39:53Z"
- Name
- failedAt
- Type
- nullable string
- Description
Time when the porting was failed.
Example:"2021-01-21T19:39:53Z"
- Name
- failureReason
- Type
- nullable string
- Description
The reason for the porting failure. Only recorded when the porting failed because user consent could not be obtained.
Example:"consentNotGiven"Allowed values:consentCodeAttemptsExceededconsentNotGivenconsentRequestCanceled
- Name
- firstName
- Type
- nullable string
- Description
The first name of the account holder on the donor service provider.
Example:"Jerry"
- Name
- lastDeclinedAt
- Type
- nullable string
- Description
Time when the porting was last declined.
Example:"2021-01-21T19:31:13Z"
- Name
- lastName
- Type
- nullable string
- Description
The last name of the account holder on the donor service provider.
Example:"Seinfeld"
- Name
- lastRequestedAt
- Type
- nullable string
- Description
Time when the porting was last requested.
Example:"2021-01-21T19:22:31Z"
- Name
- phoneNumber
- Type
- string
- Description
The phone number to port in E.164 string_format.
Example:"+19591234567"
- Name
- provider
- Type
- string
- Description
The ID of the recipient network provider.
Example:"p9"
- Name
- recipientProvider
- Type
- ServiceProvider
- Description
- The service provider to whom the number is ported.
- Name
- requestBehavior
- Type
- string
- Status
- PREVIEW
- Description
Controls when the porting is submitted to the recipient network provider.
When
automatic, the porting is requested automatically as soon as all required information is present.When
manual, that automatic submission is withheld until the porting is requested explicitly via the request a porting endpoint. Amanualporting that has all required information waits in theinformationRequiredstatus, or indeclinedif it was declined, until it is requested.Example:"automatic"Allowed values:automaticmanual
- Name
- required
- Type
- array
- Description
List of fields required for the porting to be processable. The fields depend on the donor and recipient providers.
Example:["accountNumber","accountPin","accountType","address","birthday","donorProvider","donorProviderApproval","firstName","lastName"]
- Name
- scheduledOn
- Type
- nullable string
- Description
Date when the porting is scheduled to take effect.
For most providers this returns the provider-confirmed date when available, otherwise the user-requested date. For Concierge scheduled porting (p18), this returns the user-facing expected completion date and does not reflect the internal batch run date.
Scheduling a port-in is only supported in France, Ireland, Sweden and the United Kingdom. For other regions this reflects the provider-confirmed date when available or
nullotherwise.Example:"2021-01-21"
- Name
- status
- Type
- string
- Description
The current status of the porting.
Allowed values:draftinitiatedpendinginformationRequiredrequesteddeclinedcompletedcanceledexpiredfailed
- 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
curl https://api.gigs.com/projects/${GIGS_PROJECT}/portings/{porting}/cancel \
-X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${GIGS_TOKEN}" \
-H "Accept: application/json"
Response 200
{
"object": "porting",
"id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS",
"accountNumber": "123456789",
"accountPinExists": true,
"accountType": "prepaidUnregistered",
"address": {
"city": "New York City",
"country": "US",
"line1": "129 West 81st Street",
"line2": "Apartment 5",
"postalCode": "10024",
"state": "NY"
},
"behavior": "portIn",
"billingPinExists": true,
"birthday": "2017-07-21",
"canceledAt": "2021-01-21T19:39:53Z",
"completedAt": "2021-01-21T19:36:57Z",
"createdAt": "2021-01-21T19:12:28Z",
"declinedAttempts": 0,
"declinedCode": "portingPhoneNumberPortProtected",
"declinedMessage": "The phone number has port protection on the provider.",
"donorProvider": {
"object": "serviceProvider",
"id": "svp_0SNlurA01K6GY5L0XJffY8",
"country": "US",
"name": "AT&T",
"recipientProviders": [
"p3"
]
},
"donorProviderApproval": true,
"expiredAt": "2021-01-21T19:39:53Z",
"failedAt": "2021-01-21T19:39:53Z",
"failureReason": "consentNotGiven",
"firstName": "Jerry",
"lastDeclinedAt": "2021-01-21T19:31:13Z",
"lastName": "Seinfeld",
"lastRequestedAt": "2021-01-21T19:22:31Z",
"phoneNumber": "+19591234567",
"provider": "p9",
"recipientProvider": {
"object": "serviceProvider",
"id": "svp_0SNlurA01K6GY5L0XJffY8",
"country": "US",
"name": "AT&T",
"recipientProviders": [
"p3"
]
},
"requestBehavior": "automatic",
"required": [
"accountNumber",
"accountPin",
"accountType",
"address",
"birthday",
"donorProvider",
"donorProviderApproval",
"firstName",
"lastName"
],
"scheduledOn": "2021-01-21",
"status": "draft",
"subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
"user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
}
Request a porting
Requests a porting from the recipient network provider.
Only portings with a requestBehavior of manual can be requested with this endpoint. The porting must be in the informationRequired or declined status, have all required information and be attached to a subscription that is pending or active.
Related guide: How Porting Works
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
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
- accountType
- Type
- nullable string
- Description
The type of account on the donor service provider. This field is only used for portings in Ireland and may be
nullotherwise.Example:"prepaidUnregistered"Allowed values:postpaidMultipostpaidSingleprepaidRegisteredprepaidUnregistered
- Name
- address
- Type
- nullable object
- Description
- The address of the account holder on the donor service provider.
- Name
- behavior
- Type
- string
- Description
The behavior of the porting.
A value of
portInindicates that this porting will transfer the phone number from the previous provider.A porting with behavior
cancelOnlywill 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:cancelOnlyportIn
- Name
- billingPinExists
- Type
- boolean
- Description
Whether the billing PIN has been provided.
Example:true
- Name
- birthday
- Type
- nullable string
- Description
The birthday of the account holder on the donor service provider.
Example:"2017-07-21"
- Name
- canceledAt
- Type
- nullable string
- Description
Time when the porting was canceled.
Example:"2021-01-21T19:39:53Z"
- Name
- completedAt
- Type
- nullable string
- Description
Time when the porting was completed.
Example:"2021-01-21T19:36:57Z"
- Name
- createdAt
- Type
- string
- Description
Time when the porting was created.
Example:"2021-01-21T19:12:28Z"
- Name
- declinedAttempts
- Type
- integer
- Description
The number of declined porting attempts so far.
Example:0>= 0
- Name
- declinedCode
- Type
- nullable string
- Description
The code reason for the declined porting.
Example:"portingPhoneNumberPortProtected"
- Name
- declinedMessage
- Type
- nullable string
- Description
The reason description for the declined porting.
Example:"The phone number has port protection on the provider."
- Name
- donorProvider
- Type
- nullable ServiceProvider
- Description
- The service provider from whom the number is ported.
- Name
- donorProviderApproval
- Type
- nullable boolean
- Description
Whether the donor provider has approved or not the porting.
Example:true
- Name
- expiredAt
- Type
- nullable string
- Description
Time when the porting was expired.
Example:"2021-01-21T19:39:53Z"
- Name
- failedAt
- Type
- nullable string
- Description
Time when the porting was failed.
Example:"2021-01-21T19:39:53Z"
- Name
- failureReason
- Type
- nullable string
- Description
The reason for the porting failure. Only recorded when the porting failed because user consent could not be obtained.
Example:"consentNotGiven"Allowed values:consentCodeAttemptsExceededconsentNotGivenconsentRequestCanceled
- Name
- firstName
- Type
- nullable string
- Description
The first name of the account holder on the donor service provider.
Example:"Jerry"
- Name
- lastDeclinedAt
- Type
- nullable string
- Description
Time when the porting was last declined.
Example:"2021-01-21T19:31:13Z"
- Name
- lastName
- Type
- nullable string
- Description
The last name of the account holder on the donor service provider.
Example:"Seinfeld"
- Name
- lastRequestedAt
- Type
- nullable string
- Description
Time when the porting was last requested.
Example:"2021-01-21T19:22:31Z"
- Name
- phoneNumber
- Type
- string
- Description
The phone number to port in E.164 string_format.
Example:"+19591234567"
- Name
- provider
- Type
- string
- Description
The ID of the recipient network provider.
Example:"p9"
- Name
- recipientProvider
- Type
- ServiceProvider
- Description
- The service provider to whom the number is ported.
- Name
- requestBehavior
- Type
- string
- Status
- PREVIEW
- Description
Controls when the porting is submitted to the recipient network provider.
When
automatic, the porting is requested automatically as soon as all required information is present.When
manual, that automatic submission is withheld until the porting is requested explicitly via the request a porting endpoint. Amanualporting that has all required information waits in theinformationRequiredstatus, or indeclinedif it was declined, until it is requested.Example:"automatic"Allowed values:automaticmanual
- Name
- required
- Type
- array
- Description
List of fields required for the porting to be processable. The fields depend on the donor and recipient providers.
Example:["accountNumber","accountPin","accountType","address","birthday","donorProvider","donorProviderApproval","firstName","lastName"]
- Name
- scheduledOn
- Type
- nullable string
- Description
Date when the porting is scheduled to take effect.
For most providers this returns the provider-confirmed date when available, otherwise the user-requested date. For Concierge scheduled porting (p18), this returns the user-facing expected completion date and does not reflect the internal batch run date.
Scheduling a port-in is only supported in France, Ireland, Sweden and the United Kingdom. For other regions this reflects the provider-confirmed date when available or
nullotherwise.Example:"2021-01-21"
- Name
- status
- Type
- string
- Description
The current status of the porting.
Allowed values:draftinitiatedpendinginformationRequiredrequesteddeclinedcompletedcanceledexpiredfailed
- 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
curl https://api.gigs.com/projects/${GIGS_PROJECT}/portings/{porting}/request \
-X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${GIGS_TOKEN}" \
-H "Accept: application/json"
Response 200
{
"object": "porting",
"id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS",
"accountNumber": "123456789",
"accountPinExists": true,
"accountType": "prepaidUnregistered",
"address": {
"city": "New York City",
"country": "US",
"line1": "129 West 81st Street",
"line2": "Apartment 5",
"postalCode": "10024",
"state": "NY"
},
"behavior": "portIn",
"billingPinExists": true,
"birthday": "2017-07-21",
"canceledAt": "2021-01-21T19:39:53Z",
"completedAt": "2021-01-21T19:36:57Z",
"createdAt": "2021-01-21T19:12:28Z",
"declinedAttempts": 0,
"declinedCode": "portingPhoneNumberPortProtected",
"declinedMessage": "The phone number has port protection on the provider.",
"donorProvider": {
"object": "serviceProvider",
"id": "svp_0SNlurA01K6GY5L0XJffY8",
"country": "US",
"name": "AT&T",
"recipientProviders": [
"p3"
]
},
"donorProviderApproval": true,
"expiredAt": "2021-01-21T19:39:53Z",
"failedAt": "2021-01-21T19:39:53Z",
"failureReason": "consentNotGiven",
"firstName": "Jerry",
"lastDeclinedAt": "2021-01-21T19:31:13Z",
"lastName": "Seinfeld",
"lastRequestedAt": "2021-01-21T19:22:31Z",
"phoneNumber": "+19591234567",
"provider": "p9",
"recipientProvider": {
"object": "serviceProvider",
"id": "svp_0SNlurA01K6GY5L0XJffY8",
"country": "US",
"name": "AT&T",
"recipientProviders": [
"p3"
]
},
"requestBehavior": "automatic",
"required": [
"accountNumber",
"accountPin",
"accountType",
"address",
"birthday",
"donorProvider",
"donorProviderApproval",
"firstName",
"lastName"
],
"scheduledOn": "2021-01-21",
"status": "draft",
"subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
"user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
}
Search for portings
Searches for existing portings matching the given parameters.
Body
- Name
- phoneNumber
- Type
- string
- Description
The E.164-formatted phone number associated with the porting.
Example:"+12065550123"
required
Path Parameters
Responses
Returns a list of portings matching the search criteria.
- 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
afterpagination 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
beforepagination parameter if more items are available sorted before the current batch of items.
Request
curl https://api.gigs.com/projects/${GIGS_PROJECT}/portings/search \
-X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${GIGS_TOKEN}" \
-H "Accept: application/json" \
-d '{
"phoneNumber": "+12065550123"
}'
Responses 200
{
"object": "list",
"items": [
{
"object": "porting",
"id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS",
"accountNumber": "123456789",
"accountPinExists": true,
"accountType": "prepaidUnregistered",
"address": {
"city": "New York City",
"country": "US",
"line1": "129 West 81st Street",
"line2": "Apartment 5",
"postalCode": "10024",
"state": "NY"
},
"behavior": "portIn",
"billingPinExists": true,
"birthday": "2017-07-21",
"canceledAt": "2021-01-21T19:39:53Z",
"completedAt": "2021-01-21T19:36:57Z",
"createdAt": "2021-01-21T19:12:28Z",
"declinedAttempts": 0,
"declinedCode": "portingPhoneNumberPortProtected",
"declinedMessage": "The phone number has port protection on the provider.",
"donorProvider": {
"object": "serviceProvider",
"id": "svp_0SNlurA01K6GY5L0XJffY8",
"country": "US",
"name": "AT&T",
"recipientProviders": [
"p3"
]
},
"donorProviderApproval": true,
"expiredAt": "2021-01-21T19:39:53Z",
"failedAt": "2021-01-21T19:39:53Z",
"failureReason": "consentNotGiven",
"firstName": "Jerry",
"lastDeclinedAt": "2021-01-21T19:31:13Z",
"lastName": "Seinfeld",
"lastRequestedAt": "2021-01-21T19:22:31Z",
"phoneNumber": "+19591234567",
"provider": "p9",
"recipientProvider": {
"object": "serviceProvider",
"id": "svp_0SNlurA01K6GY5L0XJffY8",
"country": "US",
"name": "AT&T",
"recipientProviders": [
"p3"
]
},
"requestBehavior": "automatic",
"required": [
"accountNumber",
"accountPin",
"accountType",
"address",
"birthday",
"donorProvider",
"donorProviderApproval",
"firstName",
"lastName"
],
"scheduledOn": "2021-01-21",
"status": "draft",
"subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
"user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
}
],
"moreItemsAfter": null,
"moreItemsBefore": null
}
List all service providers
Returns a list of service providers. It is recommended that callers provide either a recipient provider or country to filter for relevant 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"
- Name
- country
- Type
- string
- Description
Only return service providers for the given country represented by the ISO 3166-1 alpha-2 country code.
Example:"US"
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
afterpagination 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
beforepagination parameter if more items are available sorted before the current batch of items.
Request
curl https://api.gigs.com/serviceProviders \
-X GET \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${GIGS_TOKEN}" \
-H "Accept: application/json"
Responses 200
{
"object": "list",
"items": [
{
"object": "serviceProvider",
"id": "svp_0SNlurA01K6GY5L0XJffY8",
"country": "US",
"name": "AT&T",
"recipientProviders": [
"p3"
]
}
],
"moreItemsAfter": null,
"moreItemsBefore": null
}
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
- Description
The unique identifier for the service provider.
Example:"svp_0SNlurA01K6GY5L0XJffY8"
required
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
- country
- Type
- string
- Description
The ISO 3166-1 alpha-2 country code of the service provider.
Example:"US"
- 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
curl https://api.gigs.com/serviceProviders/{serviceProvider} \
-X GET \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${GIGS_TOKEN}" \
-H "Accept: application/json"
Response 200
{
"object": "serviceProvider",
"id": "svp_0SNlurA01K6GY5L0XJffY8",
"country": "US",
"name": "AT&T",
"recipientProviders": [
"p3"
]
}