# Port Outs

## The PortOut object

Port out is required when a user wants to keep their number when cancelling their subscription. There are multiple steps involved between the user, the current carrier, and the new carrier.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `object` | string | Yes | Type of object is always `portOut`. |
| `id` | string | Yes | Unique identifier for the port out. |
| `behavior` | cancelOnly | portOut | Yes | The behavior of the port out.  A value of `portOut` indicates that using this port out will transfer the phone number to the recipient provider.  Port out with behavior `cancelOnly` will cancel the service without transferring the number. This behavior is currently only available for local plans in the United Kingdom.  |
| `completedAt` | string,null | Yes | Time when the port out is completed successfully. |
| `createdAt` | string | Yes | Time when the port out was created. |
| `expiredAt` | string,null | Yes | Time when the port out expires and won't be valid anymore. |
| `failureReason` | null | consentNotGiven | consentRequestCanceled | Yes | The reason for the port out failure. |
| `status` | completed | expired | failed | initiated | issued | processing | Yes | The current status of the port out. |
| `subscription` | string | Yes | Unique identifier of the subscription affected. |
| `user` | string | Yes | Unique identifier for the user this port out credentials are for. |

---

## List all port outs

`GET /projects/{project}/portOuts`

Returns a list of port outs.

### 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 |
|------|------|----------|-------------|
| `subscription` | string | No | The unique identifier of the subscription to be filtered by. |
| `status` | string[] | No | A comma-separated list of statuses to filter the port outs by. Only initiated, processing and issued port outs are returned by default. |
| `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 port outs.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `object` | string | Yes | Type of object is always `list`. |
| `items` | object[] | Yes | List of objects of type `portOut`. |
| `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.  <!-- theme: info --> > #### 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 port out

`POST /projects/{project}/portOuts`

Create a new port out.

### Body

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `behavior` | cancelOnly | portOut | No | The behavior of the port out.  A value of `portOut` indicates that using this port out will transfer the phone number to the recipient provider.  Port out with behavior `cancelOnly` will cancel the service without transferring the number. This behavior is currently only available for local plans in the United Kingdom.  Defaults to `portOut` if no value is provided.  |
| `subscription` | string | Yes | Unique identifier of the subscription the port out applies to. |

### 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 port out.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `object` | string | Yes | Type of object is always `portOut`. |
| `id` | string | Yes | Unique identifier for the port out. |
| `behavior` | cancelOnly | portOut | Yes | The behavior of the port out.  A value of `portOut` indicates that using this port out will transfer the phone number to the recipient provider.  Port out with behavior `cancelOnly` will cancel the service without transferring the number. This behavior is currently only available for local plans in the United Kingdom.  |
| `completedAt` | string,null | Yes | Time when the port out is completed successfully. |
| `createdAt` | string | Yes | Time when the port out was created. |
| `expiredAt` | string,null | Yes | Time when the port out expires and won't be valid anymore. |
| `failureReason` | null | consentNotGiven | consentRequestCanceled | Yes | The reason for the port out failure. |
| `status` | completed | expired | failed | initiated | issued | processing | Yes | The current status of the port out. |
| `subscription` | string | Yes | Unique identifier of the subscription affected. |
| `user` | string | Yes | Unique identifier for the user this port out credentials are 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.  <!-- theme: info --> > #### 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 port out

`GET /projects/{project}/portOuts/{portOut}`

Retrieves the details of an existing port out.

### Path Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `project` | string | Yes | The unique identifier for the [project](https://developers.gigs.com/core/projects#the-project-resource). |
| `portOut` | string | Yes | The unique identifier for the port out. |

### Responses

#### 200 — Returns the port out.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `object` | string | Yes | Type of object is always `portOut`. |
| `id` | string | Yes | Unique identifier for the port out. |
| `behavior` | cancelOnly | portOut | Yes | The behavior of the port out.  A value of `portOut` indicates that using this port out will transfer the phone number to the recipient provider.  Port out with behavior `cancelOnly` will cancel the service without transferring the number. This behavior is currently only available for local plans in the United Kingdom.  |
| `completedAt` | string,null | Yes | Time when the port out is completed successfully. |
| `createdAt` | string | Yes | Time when the port out was created. |
| `expiredAt` | string,null | Yes | Time when the port out expires and won't be valid anymore. |
| `failureReason` | null | consentNotGiven | consentRequestCanceled | Yes | The reason for the port out failure. |
| `status` | completed | expired | failed | initiated | issued | processing | Yes | The current status of the port out. |
| `subscription` | string | Yes | Unique identifier of the subscription affected. |
| `user` | string | Yes | Unique identifier for the user this port out credentials are 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.  <!-- theme: info --> > #### 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.  <!-- theme: info --> > #### 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 port out credentials

`GET /projects/{project}/portOuts/{portOut}/credentials`

Retrieve the credentials of an issued port out.

### Path Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `project` | string | Yes | The unique identifier for the [project](https://developers.gigs.com/core/projects#the-project-resource). |
| `portOut` | string | Yes | The unique identifier for the port out. |

### Responses

#### 200 — Returns the port out credentials.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `object` | string | Yes | Type of object is always `portOutCredentials`. |
| `accountNumber` | string,null | Yes | The account number on the service provider. Account number is `null` if no account number is issued in the respective country. |
| `accountPin` | string | Yes | The account pin from the service provider. |
| `portOut` | string | Yes | Unique identifier of the port out this credentials are for. |

#### 403 — The authenticated user doesn't have permissions to perform the request.

| 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.  <!-- theme: info --> > #### 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. |

#### 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.  <!-- theme: info --> > #### 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.  <!-- theme: info --> > #### 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. |

---

## Expire existing port out credentials

`POST /projects/{project}/portOuts/{portOut}/expire`

Expires the port out, making the credentials unusable. Port outs with a status of `"initiated"`, `"processing"` or `"issued"` can be expired.

### Path Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `project` | string | Yes | The unique identifier for the [project](https://developers.gigs.com/core/projects#the-project-resource). |
| `portOut` | string | Yes | The unique identifier for the port out. |

### Responses

#### 200 — Returns the port out

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `object` | string | Yes | Type of object is always `portOut`. |
| `id` | string | Yes | Unique identifier for the port out. |
| `behavior` | cancelOnly | portOut | Yes | The behavior of the port out.  A value of `portOut` indicates that using this port out will transfer the phone number to the recipient provider.  Port out with behavior `cancelOnly` will cancel the service without transferring the number. This behavior is currently only available for local plans in the United Kingdom.  |
| `completedAt` | string,null | Yes | Time when the port out is completed successfully. |
| `createdAt` | string | Yes | Time when the port out was created. |
| `expiredAt` | string,null | Yes | Time when the port out expires and won't be valid anymore. |
| `failureReason` | null | consentNotGiven | consentRequestCanceled | Yes | The reason for the port out failure. |
| `status` | completed | expired | failed | initiated | issued | processing | Yes | The current status of the port out. |
| `subscription` | string | Yes | Unique identifier of the subscription affected. |
| `user` | string | Yes | Unique identifier for the user this port out credentials are 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.  <!-- theme: info --> > #### 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.  <!-- theme: info --> > #### 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. |

---

## Simulate port out completion by network provider

`POST /testing/projects/{project}/portOuts/{portOut}/simulate`

Simulates completion of a port out for a subscription with a test SIM. Can be used to test complete flow of a successful port out with end of subscription.

> **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 |
|------|------|----------|-------------|
| `project` | string | Yes | The unique identifier for the [project](https://developers.gigs.com/core/projects#the-project-resource). |
| `portOut` | string | Yes | The unique identifier for the port out. |

### Responses

#### 200 — Port out completed successfully.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `object` | string | Yes | Type of object is always `portOut`. |
| `id` | string | Yes | Unique identifier for the port out. |
| `behavior` | cancelOnly | portOut | Yes | The behavior of the port out.  A value of `portOut` indicates that using this port out will transfer the phone number to the recipient provider.  Port out with behavior `cancelOnly` will cancel the service without transferring the number. This behavior is currently only available for local plans in the United Kingdom.  |
| `completedAt` | string,null | Yes | Time when the port out is completed successfully. |
| `createdAt` | string | Yes | Time when the port out was created. |
| `expiredAt` | string,null | Yes | Time when the port out expires and won't be valid anymore. |
| `failureReason` | null | consentNotGiven | consentRequestCanceled | Yes | The reason for the port out failure. |
| `status` | completed | expired | failed | initiated | issued | processing | Yes | The current status of the port out. |
| `subscription` | string | Yes | Unique identifier of the subscription affected. |
| `user` | string | Yes | Unique identifier for the user this port out credentials are 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.  <!-- theme: info --> > #### 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.  <!-- theme: info --> > #### 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. |

---