# Portings ## The Porting object 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 | Property | Type | Required | Description | |----------|------|----------|-------------| | `object` | string | Yes | Type of object is always `porting`. | | `id` | string | Yes | Unique identifier for the porting. | | `accountNumber` | string,null | Yes | The account number on the donor service provider. | | `accountPinExists` | boolean | Yes | Whether the account PIN has been provided. | | `accountType` | null | postpaidMulti | postpaidSingle | prepaidRegistered | prepaidUnregistered | Yes | The type of account on the donor service provider. This field is only used for portings in Ireland and may be `null` otherwise. | | `address` | object,null | Yes | The address of the account holder on the donor service provider. | | `behavior` | cancelOnly | portIn | Yes | The behavior of the porting. A value of `portIn` indicates that this porting will transfer the phone number from the previous provider. A porting with behavior `cancelOnly` will cancel the previous service without transferring the number. This behavior is currently only available for local plans in the United Kingdom. | | `billingPinExists` | boolean | Yes | Whether the billing PIN has been provided. | | `birthday` | string,null | Yes | The birthday of the account holder on the donor service provider. | | `canceledAt` | string,null | Yes | Time when the porting was canceled. | | `completedAt` | string,null | Yes | Time when the porting was completed. | | `createdAt` | string | Yes | Time when the porting was created. | | `declinedAttempts` | integer | Yes | The number of declined porting attempts so far. | | `declinedCode` | string,null | Yes | The code reason for the declined porting. | | `declinedMessage` | string,null | Yes | The reason description for the declined porting. | | `donorProvider` | mixed | Yes | The service provider from whom the number is ported. | | `donorProviderApproval` | boolean,null | Yes | Whether the donor provider has approved or not the porting. | | `expiredAt` | string,null | Yes | Time when the porting was expired. | | `failedAt` | string,null | Yes | Time when the porting was failed. | | `firstName` | string,null | Yes | The first name of the account holder on the donor service provider. | | `lastDeclinedAt` | string,null | Yes | Time when the porting was last declined. | | `lastName` | string,null | Yes | The last name of the account holder on the donor service provider. | | `lastRequestedAt` | string,null | Yes | Time when the porting was last requested. | | `phoneNumber` | string | Yes | The phone number to port in E.164 string_format. | | `provider` | string | Yes | The ID of the recipient network provider. | | `recipientProvider` | object | Yes | The service provider to whom the number is ported. | | `required` | string[] | Yes | List of fields required for the porting to be processable. The fields depend on the donor and recipient providers. | | `scheduledOn` | string,null | Yes | Date when the porting is scheduled to take effect. This returns the provider-confirmed date when available, otherwise the user-requested date. The ability to schedule portings is only available for local plans in the United Kingdom. Otherwise, this value will be null. | | `status` | draft | initiated | pending | informationRequired | requested | declined | completed | canceled | expired | failed | Yes | The current status of the porting. | | `subscription` | string,null | Yes | Unique identifier for the porting subscription. | | `user` | string | Yes | Unique identifier for the user this porting is for. | --- ## List all portings `GET /projects/{project}/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 | Type | Required | Description | |------|------|----------|-------------| | `project` | string | Yes | The unique identifier for the [project](https://developers.gigs.com/core/projects#the-project-resource). | ### Query Parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `status` | string[] | No | The status to filter the portings by. | | `subscription` | string | No | The unique identifier of the subscription to be filtered by. | | `user` | string | No | The unique identifier of the user to be filtered by. | | `after` | string | No | 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. | | `before` | string | No | 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. | | `limit` | integer | No | The limit of items to be returned in the list, between 0 and 200. | ### Responses #### 200 — Returns a dictionary with an items property that contains an array of portings. | Property | Type | Required | Description | |----------|------|----------|-------------| | `object` | string | Yes | Type of object is always `list`. | | `items` | object[] | Yes | List of objects of type `porting`. | | `moreItemsAfter` | string,null | Yes | A unique identifier to be used as `after` pagination parameter if more items are available sorted after the current batch of items. | | `moreItemsBefore` | string,null | Yes | A unique identifier to be used as `before` pagination parameter if more items are available sorted before the current batch of items. | #### 422 — The request can't be processed, often due to an invalid parameter or incompatible system state. | Property | Type | Required | Description | |----------|------|----------|-------------| | `object` | string | Yes | Type of object is always `error`. | | `code` | string | No | An optional machine-readable description of the error. Present for errors that could be handled programmatically. | | `details` | object[] | No | Optional array containing specific information for the current error. > #### Preview > > This property 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](mailto:support@gigs.com) to share your thoughts. | | `documentation` | string[] | No | An optional list of URLs providing further information to resolve the error. | | `hint` | string | No | An optional explanation how to resolve the error. | | `message` | string | Yes | A human readable description of the error. | | `type` | string | Yes | The type of [error](https://developers.gigs.com/api/error-handling) returned. | --- ## Create a porting `POST /projects/{project}/portings` 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](https://developers.gigs.com/docs/porting/how-porting-in-works) ### Body | Property | Type | Required | Description | |----------|------|----------|-------------| | `accountNumber` | string,null | No | The account number on the donor service provider. | | `accountPin` | string,null | No | The pin for the account on the donor service provider. This will be used only for the porting. | | `accountType` | null | postpaidMulti | postpaidSingle | prepaidRegistered | prepaidUnregistered | No | The type of account on the donor service provider. Required for portings in Ireland. | | `address` | object,null | No | The address of the account holder on the donor service provider. | | `behavior` | cancelOnly | portIn | No | The behavior of the porting. Use `portIn` to transfer the phone number from the previous provider. Use `cancelOnly` to cancel the previous service without transferring the number. This behavior is currently only available for local plans in the United Kingdom. Defaults to `portIn` if no value is provided. > #### Preview > > This property 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](mailto:support@gigs.com) to share your thoughts. | | `billingPin` | string,null | No | The billing pin for the account on the donor service provider. This will be used only for the porting. > #### Preview > > This property 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](mailto:support@gigs.com) to share your thoughts. | | `birthday` | string,null | No | The birthday of the account holder on the donor service provider. | | `donorProvider` | string,null | No | The unique identifier of the donor service provider. | | `donorProviderApproval` | boolean,null | No | Whether the donor provider has approved or not the porting. | | `firstName` | string,null | No | The first name of the account holder. | | `lastName` | string,null | No | The last name of the account holder. | | `phoneNumber` | string | Yes | The phone number to port in E.164 string_format. | | `provider` | string | Yes | The name of the receiving network provider. | | `scheduledOn` | string,null | No | The date that the porting is scheduled to take effect. This functionality is only available for local plans in the United Kingdom. Attempting to schedule a porting for a provider in any other country will result in an error. Use `null` to indicate that the porting should be scheduled as soon as possible. Otherwise, the date provided must be in the future. If, by the time the porting is used to create a subscription, the scheduled date has already passed, then the porting will instead occur as soon as possible. > #### Preview > > This property 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](mailto:support@gigs.com) to share your thoughts. | | `user` | string | Yes | The unique identifier for an existing [user](https://developers.gigs.com/core/users#the-user-resource) the porting should be created for. | ### Path Parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `project` | string | Yes | The unique identifier for the [project](https://developers.gigs.com/core/projects#the-project-resource). | ### Responses #### 201 — Returns the created porting. | Property | Type | Required | Description | |----------|------|----------|-------------| | `object` | string | Yes | Type of object is always `porting`. | | `id` | string | Yes | Unique identifier for the porting. | | `accountNumber` | string,null | Yes | The account number on the donor service provider. | | `accountPinExists` | boolean | Yes | Whether the account PIN has been provided. | | `accountType` | null | postpaidMulti | postpaidSingle | prepaidRegistered | prepaidUnregistered | Yes | The type of account on the donor service provider. This field is only used for portings in Ireland and may be `null` otherwise. | | `address` | object,null | Yes | The address of the account holder on the donor service provider. | | `behavior` | cancelOnly | portIn | Yes | The behavior of the porting. A value of `portIn` indicates that this porting will transfer the phone number from the previous provider. A porting with behavior `cancelOnly` will cancel the previous service without transferring the number. This behavior is currently only available for local plans in the United Kingdom. | | `billingPinExists` | boolean | Yes | Whether the billing PIN has been provided. | | `birthday` | string,null | Yes | The birthday of the account holder on the donor service provider. | | `canceledAt` | string,null | Yes | Time when the porting was canceled. | | `completedAt` | string,null | Yes | Time when the porting was completed. | | `createdAt` | string | Yes | Time when the porting was created. | | `declinedAttempts` | integer | Yes | The number of declined porting attempts so far. | | `declinedCode` | string,null | Yes | The code reason for the declined porting. | | `declinedMessage` | string,null | Yes | The reason description for the declined porting. | | `donorProvider` | mixed | Yes | The service provider from whom the number is ported. | | `donorProviderApproval` | boolean,null | Yes | Whether the donor provider has approved or not the porting. | | `expiredAt` | string,null | Yes | Time when the porting was expired. | | `failedAt` | string,null | Yes | Time when the porting was failed. | | `firstName` | string,null | Yes | The first name of the account holder on the donor service provider. | | `lastDeclinedAt` | string,null | Yes | Time when the porting was last declined. | | `lastName` | string,null | Yes | The last name of the account holder on the donor service provider. | | `lastRequestedAt` | string,null | Yes | Time when the porting was last requested. | | `phoneNumber` | string | Yes | The phone number to port in E.164 string_format. | | `provider` | string | Yes | The ID of the recipient network provider. | | `recipientProvider` | object | Yes | The service provider to whom the number is ported. | | `required` | string[] | Yes | List of fields required for the porting to be processable. The fields depend on the donor and recipient providers. | | `scheduledOn` | string,null | Yes | Date when the porting is scheduled to take effect. This returns the provider-confirmed date when available, otherwise the user-requested date. The ability to schedule portings is only available for local plans in the United Kingdom. Otherwise, this value will be null. | | `status` | draft | initiated | pending | informationRequired | requested | declined | completed | canceled | expired | failed | Yes | The current status of the porting. | | `subscription` | string,null | Yes | Unique identifier for the porting subscription. | | `user` | string | Yes | Unique identifier for the user this porting is for. | #### 422 — The request can't be processed, often due to an invalid parameter or incompatible system state. | Property | Type | Required | Description | |----------|------|----------|-------------| | `object` | string | Yes | Type of object is always `error`. | | `code` | string | No | An optional machine-readable description of the error. Present for errors that could be handled programmatically. | | `details` | object[] | No | Optional array containing specific information for the current error. > #### Preview > > This property 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](mailto:support@gigs.com) to share your thoughts. | | `documentation` | string[] | No | An optional list of URLs providing further information to resolve the error. | | `hint` | string | No | An optional explanation how to resolve the error. | | `message` | string | Yes | A human readable description of the error. | | `type` | string | Yes | The type of [error](https://developers.gigs.com/api/error-handling) returned. | #### 503 — The network provider required to perform the request is currently unavailable. Please check [documentation](https://developers.gigs.com/api/error-handling#common-errors) for details on how to handle this error. | Property | Type | Required | Description | |----------|------|----------|-------------| | `object` | string | Yes | Type of object is always `error`. | | `code` | string | No | An optional machine-readable description of the error. Present for errors that could be handled programmatically. | | `details` | object[] | No | Optional array containing specific information for the current error. > #### Preview > > This property 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](mailto:support@gigs.com) to share your thoughts. | | `documentation` | string[] | No | An optional list of URLs providing further information to resolve the error. | | `hint` | string | No | An optional explanation how to resolve the error. | | `message` | string | Yes | A human readable description of the error. | | `type` | string | Yes | The type of [error](https://developers.gigs.com/api/error-handling) returned. | --- ## Retrieve a Porting `GET /projects/{project}/portings/{porting}` Retrieves the details of an existing porting. ### Path Parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `project` | string | Yes | The unique identifier for the [project](https://developers.gigs.com/core/projects#the-project-resource). | | `porting` | string | Yes | The unique identifier for the porting. | ### Responses #### 200 — Returns the porting. | Property | Type | Required | Description | |----------|------|----------|-------------| | `object` | string | Yes | Type of object is always `porting`. | | `id` | string | Yes | Unique identifier for the porting. | | `accountNumber` | string,null | Yes | The account number on the donor service provider. | | `accountPinExists` | boolean | Yes | Whether the account PIN has been provided. | | `accountType` | null | postpaidMulti | postpaidSingle | prepaidRegistered | prepaidUnregistered | Yes | The type of account on the donor service provider. This field is only used for portings in Ireland and may be `null` otherwise. | | `address` | object,null | Yes | The address of the account holder on the donor service provider. | | `behavior` | cancelOnly | portIn | Yes | The behavior of the porting. A value of `portIn` indicates that this porting will transfer the phone number from the previous provider. A porting with behavior `cancelOnly` will cancel the previous service without transferring the number. This behavior is currently only available for local plans in the United Kingdom. | | `billingPinExists` | boolean | Yes | Whether the billing PIN has been provided. | | `birthday` | string,null | Yes | The birthday of the account holder on the donor service provider. | | `canceledAt` | string,null | Yes | Time when the porting was canceled. | | `completedAt` | string,null | Yes | Time when the porting was completed. | | `createdAt` | string | Yes | Time when the porting was created. | | `declinedAttempts` | integer | Yes | The number of declined porting attempts so far. | | `declinedCode` | string,null | Yes | The code reason for the declined porting. | | `declinedMessage` | string,null | Yes | The reason description for the declined porting. | | `donorProvider` | mixed | Yes | The service provider from whom the number is ported. | | `donorProviderApproval` | boolean,null | Yes | Whether the donor provider has approved or not the porting. | | `expiredAt` | string,null | Yes | Time when the porting was expired. | | `failedAt` | string,null | Yes | Time when the porting was failed. | | `firstName` | string,null | Yes | The first name of the account holder on the donor service provider. | | `lastDeclinedAt` | string,null | Yes | Time when the porting was last declined. | | `lastName` | string,null | Yes | The last name of the account holder on the donor service provider. | | `lastRequestedAt` | string,null | Yes | Time when the porting was last requested. | | `phoneNumber` | string | Yes | The phone number to port in E.164 string_format. | | `provider` | string | Yes | The ID of the recipient network provider. | | `recipientProvider` | object | Yes | The service provider to whom the number is ported. | | `required` | string[] | Yes | List of fields required for the porting to be processable. The fields depend on the donor and recipient providers. | | `scheduledOn` | string,null | Yes | Date when the porting is scheduled to take effect. This returns the provider-confirmed date when available, otherwise the user-requested date. The ability to schedule portings is only available for local plans in the United Kingdom. Otherwise, this value will be null. | | `status` | draft | initiated | pending | informationRequired | requested | declined | completed | canceled | expired | failed | Yes | The current status of the porting. | | `subscription` | string,null | Yes | Unique identifier for the porting subscription. | | `user` | string | Yes | Unique identifier for the user this porting is for. | #### 404 — The requested resource doesn't exist. | Property | Type | Required | Description | |----------|------|----------|-------------| | `object` | string | Yes | Type of object is always `error`. | | `code` | string | No | An optional machine-readable description of the error. Present for errors that could be handled programmatically. | | `details` | object[] | No | Optional array containing specific information for the current error. > #### Preview > > This property 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](mailto:support@gigs.com) to share your thoughts. | | `documentation` | string[] | No | An optional list of URLs providing further information to resolve the error. | | `hint` | string | No | An optional explanation how to resolve the error. | | `message` | string | Yes | A human readable description of the error. | | `type` | string | Yes | The type of [error](https://developers.gigs.com/api/error-handling) returned. | --- ## Delete a draft porting `DELETE /projects/{project}/portings/{porting}` Deletes a porting that is in the `draft` state. ### Path Parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `project` | string | Yes | The unique identifier for the [project](https://developers.gigs.com/core/projects#the-project-resource). | | `porting` | string | Yes | The unique identifier for the porting. | ### Responses #### 200 — Returns the porting. | Property | Type | Required | Description | |----------|------|----------|-------------| | `object` | string | Yes | Type of object is always `porting`. | | `id` | string | Yes | Unique identifier for the porting. | | `accountNumber` | string,null | Yes | The account number on the donor service provider. | | `accountPinExists` | boolean | Yes | Whether the account PIN has been provided. | | `accountType` | null | postpaidMulti | postpaidSingle | prepaidRegistered | prepaidUnregistered | Yes | The type of account on the donor service provider. This field is only used for portings in Ireland and may be `null` otherwise. | | `address` | object,null | Yes | The address of the account holder on the donor service provider. | | `behavior` | cancelOnly | portIn | Yes | The behavior of the porting. A value of `portIn` indicates that this porting will transfer the phone number from the previous provider. A porting with behavior `cancelOnly` will cancel the previous service without transferring the number. This behavior is currently only available for local plans in the United Kingdom. | | `billingPinExists` | boolean | Yes | Whether the billing PIN has been provided. | | `birthday` | string,null | Yes | The birthday of the account holder on the donor service provider. | | `canceledAt` | string,null | Yes | Time when the porting was canceled. | | `completedAt` | string,null | Yes | Time when the porting was completed. | | `createdAt` | string | Yes | Time when the porting was created. | | `declinedAttempts` | integer | Yes | The number of declined porting attempts so far. | | `declinedCode` | string,null | Yes | The code reason for the declined porting. | | `declinedMessage` | string,null | Yes | The reason description for the declined porting. | | `donorProvider` | mixed | Yes | The service provider from whom the number is ported. | | `donorProviderApproval` | boolean,null | Yes | Whether the donor provider has approved or not the porting. | | `expiredAt` | string,null | Yes | Time when the porting was expired. | | `failedAt` | string,null | Yes | Time when the porting was failed. | | `firstName` | string,null | Yes | The first name of the account holder on the donor service provider. | | `lastDeclinedAt` | string,null | Yes | Time when the porting was last declined. | | `lastName` | string,null | Yes | The last name of the account holder on the donor service provider. | | `lastRequestedAt` | string,null | Yes | Time when the porting was last requested. | | `phoneNumber` | string | Yes | The phone number to port in E.164 string_format. | | `provider` | string | Yes | The ID of the recipient network provider. | | `recipientProvider` | object | Yes | The service provider to whom the number is ported. | | `required` | string[] | Yes | List of fields required for the porting to be processable. The fields depend on the donor and recipient providers. | | `scheduledOn` | string,null | Yes | Date when the porting is scheduled to take effect. This returns the provider-confirmed date when available, otherwise the user-requested date. The ability to schedule portings is only available for local plans in the United Kingdom. Otherwise, this value will be null. | | `status` | draft | initiated | pending | informationRequired | requested | declined | completed | canceled | expired | failed | Yes | The current status of the porting. | | `subscription` | string,null | Yes | Unique identifier for the porting subscription. | | `user` | string | Yes | Unique identifier for the user this porting is for. | #### 404 — The requested resource doesn't exist. | Property | Type | Required | Description | |----------|------|----------|-------------| | `object` | string | Yes | Type of object is always `error`. | | `code` | string | No | An optional machine-readable description of the error. Present for errors that could be handled programmatically. | | `details` | object[] | No | Optional array containing specific information for the current error. > #### Preview > > This property 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](mailto:support@gigs.com) to share your thoughts. | | `documentation` | string[] | No | An optional list of URLs providing further information to resolve the error. | | `hint` | string | No | An optional explanation how to resolve the error. | | `message` | string | Yes | A human readable description of the error. | | `type` | string | Yes | The type of [error](https://developers.gigs.com/api/error-handling) returned. | #### 422 — The request can't be processed, often due to an invalid parameter or incompatible system state. | Property | Type | Required | Description | |----------|------|----------|-------------| | `object` | string | Yes | Type of object is always `error`. | | `code` | string | No | An optional machine-readable description of the error. Present for errors that could be handled programmatically. | | `details` | object[] | No | Optional array containing specific information for the current error. > #### Preview > > This property 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](mailto:support@gigs.com) to share your thoughts. | | `documentation` | string[] | No | An optional list of URLs providing further information to resolve the error. | | `hint` | string | No | An optional explanation how to resolve the error. | | `message` | string | Yes | A human readable description of the error. | | `type` | string | Yes | The type of [error](https://developers.gigs.com/api/error-handling) returned. | --- ## Update a porting `PATCH /projects/{project}/portings/{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](https://developers.gigs.com/docs/core/how-porting-in-works) ### Body | Property | Type | Required | Description | |----------|------|----------|-------------| | `accountNumber` | string | No | The account number on the donor service provider. | | `accountPin` | string | No | The pin for the account on the donor service provider. This will be used only for the porting. | | `accountType` | postpaidMulti | postpaidSingle | prepaidRegistered | prepaidUnregistered | No | The type of account on the donor service provider. Required for portings in Ireland. | | `address` | object | No | The address of the account holder on the donor service provider. | | `behavior` | cancelOnly | portIn | No | The behavior of the porting. Use `portIn` to transfer the phone number from the previous provider. Use `cancelOnly` to cancel the previous service without transferring the number. This behavior is currently only available for local plans in the United Kingdom. This property is only updatable when the porting's status is draft. > #### Preview > > This property 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](mailto:support@gigs.com) to share your thoughts. | | `billingPin` | string | No | The billing pin for the account on the donor service provider. This will be used only for the porting. > #### Preview > > This property 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](mailto:support@gigs.com) to share your thoughts. | | `birthday` | string | No | The birthday of the account holder on the donor service provider. | | `donorProvider` | string | No | The unique identifier of the donor service provider. | | `donorProviderApproval` | boolean | No | Whether the donor provider has approved or not the porting. | | `firstName` | string | No | The first name of the account holder. | | `lastName` | string | No | The last name of the account holder. | | `phoneNumber` | string | No | The phone number to port in E.164 string_format. This is only updatable when the porting is in a status of: draft | | `provider` | string | No | The ID of the recipient network provider. This is only updatable when the porting is in a status of: draft | | `scheduledOn` | string,null | No | Date when the porting is scheduled to take effect. The ability to schedule portings is only available for local plans in the United Kingdom. Attempting to schedule a porting for a provider in any other country will result in an error. Use `null` to indicate that the porting should be scheduled as soon as possible. Otherwise, the date provided must be in the future. > #### Preview > > This property 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](mailto:support@gigs.com) to share your thoughts. | ### Path Parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `project` | string | Yes | The unique identifier for the [project](https://developers.gigs.com/core/projects#the-project-resource). | | `porting` | string | Yes | The unique identifier for the porting. | ### Responses #### 200 — Returns the updated porting. | Property | Type | Required | Description | |----------|------|----------|-------------| | `object` | string | Yes | Type of object is always `porting`. | | `id` | string | Yes | Unique identifier for the porting. | | `accountNumber` | string,null | Yes | The account number on the donor service provider. | | `accountPinExists` | boolean | Yes | Whether the account PIN has been provided. | | `accountType` | null | postpaidMulti | postpaidSingle | prepaidRegistered | prepaidUnregistered | Yes | The type of account on the donor service provider. This field is only used for portings in Ireland and may be `null` otherwise. | | `address` | object,null | Yes | The address of the account holder on the donor service provider. | | `behavior` | cancelOnly | portIn | Yes | The behavior of the porting. A value of `portIn` indicates that this porting will transfer the phone number from the previous provider. A porting with behavior `cancelOnly` will cancel the previous service without transferring the number. This behavior is currently only available for local plans in the United Kingdom. | | `billingPinExists` | boolean | Yes | Whether the billing PIN has been provided. | | `birthday` | string,null | Yes | The birthday of the account holder on the donor service provider. | | `canceledAt` | string,null | Yes | Time when the porting was canceled. | | `completedAt` | string,null | Yes | Time when the porting was completed. | | `createdAt` | string | Yes | Time when the porting was created. | | `declinedAttempts` | integer | Yes | The number of declined porting attempts so far. | | `declinedCode` | string,null | Yes | The code reason for the declined porting. | | `declinedMessage` | string,null | Yes | The reason description for the declined porting. | | `donorProvider` | mixed | Yes | The service provider from whom the number is ported. | | `donorProviderApproval` | boolean,null | Yes | Whether the donor provider has approved or not the porting. | | `expiredAt` | string,null | Yes | Time when the porting was expired. | | `failedAt` | string,null | Yes | Time when the porting was failed. | | `firstName` | string,null | Yes | The first name of the account holder on the donor service provider. | | `lastDeclinedAt` | string,null | Yes | Time when the porting was last declined. | | `lastName` | string,null | Yes | The last name of the account holder on the donor service provider. | | `lastRequestedAt` | string,null | Yes | Time when the porting was last requested. | | `phoneNumber` | string | Yes | The phone number to port in E.164 string_format. | | `provider` | string | Yes | The ID of the recipient network provider. | | `recipientProvider` | object | Yes | The service provider to whom the number is ported. | | `required` | string[] | Yes | List of fields required for the porting to be processable. The fields depend on the donor and recipient providers. | | `scheduledOn` | string,null | Yes | Date when the porting is scheduled to take effect. This returns the provider-confirmed date when available, otherwise the user-requested date. The ability to schedule portings is only available for local plans in the United Kingdom. Otherwise, this value will be null. | | `status` | draft | initiated | pending | informationRequired | requested | declined | completed | canceled | expired | failed | Yes | The current status of the porting. | | `subscription` | string,null | Yes | Unique identifier for the porting subscription. | | `user` | string | Yes | Unique identifier for the user this porting is for. | #### 404 — The requested resource doesn't exist. | Property | Type | Required | Description | |----------|------|----------|-------------| | `object` | string | Yes | Type of object is always `error`. | | `code` | string | No | An optional machine-readable description of the error. Present for errors that could be handled programmatically. | | `details` | object[] | No | Optional array containing specific information for the current error. > #### Preview > > This property 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](mailto:support@gigs.com) to share your thoughts. | | `documentation` | string[] | No | An optional list of URLs providing further information to resolve the error. | | `hint` | string | No | An optional explanation how to resolve the error. | | `message` | string | Yes | A human readable description of the error. | | `type` | string | Yes | The type of [error](https://developers.gigs.com/api/error-handling) returned. | #### 422 — The request can't be processed, often due to an invalid parameter or incompatible system state. | Property | Type | Required | Description | |----------|------|----------|-------------| | `object` | string | Yes | Type of object is always `error`. | | `code` | string | No | An optional machine-readable description of the error. Present for errors that could be handled programmatically. | | `details` | object[] | No | Optional array containing specific information for the current error. > #### Preview > > This property 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](mailto:support@gigs.com) to share your thoughts. | | `documentation` | string[] | No | An optional list of URLs providing further information to resolve the error. | | `hint` | string | No | An optional explanation how to resolve the error. | | `message` | string | Yes | A human readable description of the error. | | `type` | string | Yes | The type of [error](https://developers.gigs.com/api/error-handling) returned. | #### 503 — The network provider required to perform the request is currently unavailable. Please check [documentation](https://developers.gigs.com/api/error-handling#common-errors) for details on how to handle this error. | Property | Type | Required | Description | |----------|------|----------|-------------| | `object` | string | Yes | Type of object is always `error`. | | `code` | string | No | An optional machine-readable description of the error. Present for errors that could be handled programmatically. | | `details` | object[] | No | Optional array containing specific information for the current error. > #### Preview > > This property 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](mailto:support@gigs.com) to share your thoughts. | | `documentation` | string[] | No | An optional list of URLs providing further information to resolve the error. | | `hint` | string | No | An optional explanation how to resolve the error. | | `message` | string | Yes | A human readable description of the error. | | `type` | string | Yes | The type of [error](https://developers.gigs.com/api/error-handling) returned. | --- ## Cancel a porting `POST /projects/{project}/portings/{porting}/cancel` Cancels a porting. A porting can be cancelled in the following situations: - it is in the `pending`, `declined` or `informationRequired` state, - it is in the `requested` state **and** it is scheduled for a future date. Canceling a porting will result in the activation of the subscription with a new number. To cancel the whole process, end the subscription instead. ### Path Parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `project` | string | Yes | The unique identifier for the [project](https://developers.gigs.com/core/projects#the-project-resource). | | `porting` | string | Yes | The unique identifier for the porting. | ### Responses #### 200 — Returns the canceled porting. | Property | Type | Required | Description | |----------|------|----------|-------------| | `object` | string | Yes | Type of object is always `porting`. | | `id` | string | Yes | Unique identifier for the porting. | | `accountNumber` | string,null | Yes | The account number on the donor service provider. | | `accountPinExists` | boolean | Yes | Whether the account PIN has been provided. | | `accountType` | null | postpaidMulti | postpaidSingle | prepaidRegistered | prepaidUnregistered | Yes | The type of account on the donor service provider. This field is only used for portings in Ireland and may be `null` otherwise. | | `address` | object,null | Yes | The address of the account holder on the donor service provider. | | `behavior` | cancelOnly | portIn | Yes | The behavior of the porting. A value of `portIn` indicates that this porting will transfer the phone number from the previous provider. A porting with behavior `cancelOnly` will cancel the previous service without transferring the number. This behavior is currently only available for local plans in the United Kingdom. | | `billingPinExists` | boolean | Yes | Whether the billing PIN has been provided. | | `birthday` | string,null | Yes | The birthday of the account holder on the donor service provider. | | `canceledAt` | string,null | Yes | Time when the porting was canceled. | | `completedAt` | string,null | Yes | Time when the porting was completed. | | `createdAt` | string | Yes | Time when the porting was created. | | `declinedAttempts` | integer | Yes | The number of declined porting attempts so far. | | `declinedCode` | string,null | Yes | The code reason for the declined porting. | | `declinedMessage` | string,null | Yes | The reason description for the declined porting. | | `donorProvider` | mixed | Yes | The service provider from whom the number is ported. | | `donorProviderApproval` | boolean,null | Yes | Whether the donor provider has approved or not the porting. | | `expiredAt` | string,null | Yes | Time when the porting was expired. | | `failedAt` | string,null | Yes | Time when the porting was failed. | | `firstName` | string,null | Yes | The first name of the account holder on the donor service provider. | | `lastDeclinedAt` | string,null | Yes | Time when the porting was last declined. | | `lastName` | string,null | Yes | The last name of the account holder on the donor service provider. | | `lastRequestedAt` | string,null | Yes | Time when the porting was last requested. | | `phoneNumber` | string | Yes | The phone number to port in E.164 string_format. | | `provider` | string | Yes | The ID of the recipient network provider. | | `recipientProvider` | object | Yes | The service provider to whom the number is ported. | | `required` | string[] | Yes | List of fields required for the porting to be processable. The fields depend on the donor and recipient providers. | | `scheduledOn` | string,null | Yes | Date when the porting is scheduled to take effect. This returns the provider-confirmed date when available, otherwise the user-requested date. The ability to schedule portings is only available for local plans in the United Kingdom. Otherwise, this value will be null. | | `status` | draft | initiated | pending | informationRequired | requested | declined | completed | canceled | expired | failed | Yes | The current status of the porting. | | `subscription` | string,null | Yes | Unique identifier for the porting subscription. | | `user` | string | Yes | Unique identifier for the user this porting is for. | #### 404 — The requested resource doesn't exist. | Property | Type | Required | Description | |----------|------|----------|-------------| | `object` | string | Yes | Type of object is always `error`. | | `code` | string | No | An optional machine-readable description of the error. Present for errors that could be handled programmatically. | | `details` | object[] | No | Optional array containing specific information for the current error. > #### Preview > > This property 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](mailto:support@gigs.com) to share your thoughts. | | `documentation` | string[] | No | An optional list of URLs providing further information to resolve the error. | | `hint` | string | No | An optional explanation how to resolve the error. | | `message` | string | Yes | A human readable description of the error. | | `type` | string | Yes | The type of [error](https://developers.gigs.com/api/error-handling) returned. | #### 422 — The request can't be processed, often due to an invalid parameter or incompatible system state. | Property | Type | Required | Description | |----------|------|----------|-------------| | `object` | string | Yes | Type of object is always `error`. | | `code` | string | No | An optional machine-readable description of the error. Present for errors that could be handled programmatically. | | `details` | object[] | No | Optional array containing specific information for the current error. > #### Preview > > This property 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](mailto:support@gigs.com) to share your thoughts. | | `documentation` | string[] | No | An optional list of URLs providing further information to resolve the error. | | `hint` | string | No | An optional explanation how to resolve the error. | | `message` | string | Yes | A human readable description of the error. | | `type` | string | Yes | The type of [error](https://developers.gigs.com/api/error-handling) returned. | --- ## Search for portings `POST /projects/{project}/portings/search` Searches for existing portings matching the given parameters. ### Body | Property | Type | Required | Description | |----------|------|----------|-------------| | `phoneNumber` | string | Yes | The E.164-formatted phone number associated with the porting. | ### Path Parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `project` | string | Yes | The unique identifier for the [project](https://developers.gigs.com/core/projects#the-project-resource). | ### Responses #### 200 — Returns a list of portings matching the search criteria. | Property | Type | Required | Description | |----------|------|----------|-------------| | `object` | string | Yes | Type of object is always `list`. | | `items` | object[] | Yes | List of objects of type `porting`. | | `moreItemsAfter` | string,null | Yes | A unique identifier to be used as `after` pagination parameter if more items are available sorted after the current batch of items. | | `moreItemsBefore` | string,null | Yes | A unique identifier to be used as `before` pagination parameter if more items are available sorted before the current batch of items. | #### 422 — The request can't be processed, often due to an invalid parameter or incompatible system state. | Property | Type | Required | Description | |----------|------|----------|-------------| | `object` | string | Yes | Type of object is always `error`. | | `code` | string | No | An optional machine-readable description of the error. Present for errors that could be handled programmatically. | | `details` | object[] | No | Optional array containing specific information for the current error. > #### Preview > > This property 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](mailto:support@gigs.com) to share your thoughts. | | `documentation` | string[] | No | An optional list of URLs providing further information to resolve the error. | | `hint` | string | No | An optional explanation how to resolve the error. | | `message` | string | Yes | A human readable description of the error. | | `type` | string | Yes | The type of [error](https://developers.gigs.com/api/error-handling) returned. | --- ## List all service providers `GET /serviceProviders` Returns a list of service providers. It is recommended that callers provide either a recipient provider or country to filter for relevant service providers. > **Info** > #### 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](mailto:support@gigs.com) to share your thoughts. ### Query Parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `recipientProvider` | string | No | Only return service providers that have the given network provider as supported porting recipient. | | `country` | string | No | Only return service providers for the given country represented by the ISO 3166-1 alpha-2 country code. | ### Responses #### 200 — Returns a dictionary with an items property that contains an array of service providers. | Property | Type | Required | Description | |----------|------|----------|-------------| | `object` | string | Yes | Type of object is always `list`. | | `items` | object[] | Yes | List of objects of type `serviceProvider`. | | `moreItemsAfter` | string,null | Yes | A unique identifier to be used as `after` pagination parameter if more items are available sorted after the current batch of items. | | `moreItemsBefore` | string,null | Yes | A unique identifier to be used as `before` pagination parameter if more items are available sorted before the current batch of items. | #### 422 — The request can't be processed, often due to an invalid parameter or incompatible system state. | Property | Type | Required | Description | |----------|------|----------|-------------| | `object` | string | Yes | Type of object is always `error`. | | `code` | string | No | An optional machine-readable description of the error. Present for errors that could be handled programmatically. | | `details` | object[] | No | Optional array containing specific information for the current error. > #### Preview > > This property 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](mailto:support@gigs.com) to share your thoughts. | | `documentation` | string[] | No | An optional list of URLs providing further information to resolve the error. | | `hint` | string | No | An optional explanation how to resolve the error. | | `message` | string | Yes | A human readable description of the error. | | `type` | string | Yes | The type of [error](https://developers.gigs.com/api/error-handling) returned. | --- ## Retrieve a service provider `GET /serviceProviders/{serviceProvider}` Retrieves the details of a service provider. > **Info** > #### 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](mailto:support@gigs.com) to share your thoughts. ### Path Parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `serviceProvider` | string | Yes | The unique identifier for the service provider. | ### Responses #### 200 — Returns the service provider object if it exists. | Property | Type | Required | Description | |----------|------|----------|-------------| | `object` | string | Yes | Type of object is always `serviceProvider`. | | `id` | string | Yes | Unique identifier for the service provider. | | `country` | string | Yes | The ISO 3166-1 alpha-2 country code of the service provider. | | `name` | string | Yes | The name of the service provider, usually a brand name. | | `recipientProviders` | string[] | Yes | List of network providers IDs that can receive portings from the service provider. | #### 404 — The requested resource doesn't exist. | Property | Type | Required | Description | |----------|------|----------|-------------| | `object` | string | Yes | Type of object is always `error`. | | `code` | string | No | An optional machine-readable description of the error. Present for errors that could be handled programmatically. | | `details` | object[] | No | Optional array containing specific information for the current error. > #### Preview > > This property 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](mailto:support@gigs.com) to share your thoughts. | | `documentation` | string[] | No | An optional list of URLs providing further information to resolve the error. | | `hint` | string | No | An optional explanation how to resolve the error. | | `message` | string | Yes | A human readable description of the error. | | `type` | string | Yes | The type of [error](https://developers.gigs.com/api/error-handling) returned. | ---