Port Outs

Preview

This schema 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.

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.

Properties

  • Name
    object
    Type
    string
    Description

    Type of object is always portOut.

    Allowed values: portOut 
  • Name
    id
    Type
    string
    Description

    Unique identifier for the port out.

    Example: "pto_0SNlurA049MEWV4DWEaT4SaeDI8s"
  • Name
    behavior
    Type
    string
    Description

    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.

    Example: "portOut"
    Allowed values: cancelOnly portOut 
  • Name
    createdAt
    Type
    string
    Description

    Time when the port out was created.

    Example: "2020-01-01T00:00:00Z"
  • Name
    expiredAt
    Type
    nullable string
    Description

    Time when the port out expires and won't be valid anymore.

    Example: "2022-02-21T19:38:34Z"
  • Name
    failureReason
    Type
    nullable string
    Description

    The reason for the port out failure.

    Example: "consentNotGiven"
    Allowed values: consentNotGiven consentRequestCanceled 
  • Name
    status
    Type
    string
    Description

    The current status of the port out.

    Example: "issued"
    Allowed values: expired failed initiated issued processing 
  • Name
    subscription
    Type
    string
    Description

    Unique identifier of the subscription affected.

    Example: "sub_0SNlurA049MEWV2gSfSxi00xlPIi"
  • Name
    user
    Type
    string
    Description

    Unique identifier for the user this port out credentials are for.

    Example: "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"

Example

{
  "object": "portOut",
  "id": "pto_0SNlurA049MEWV4DWEaT4SaeDI8s",
  "behavior": "portOut",
  "createdAt": "2020-01-01T01:01:01.0Z",
  "expiredAt": "2022-02-21T19:38:34Z",
  "failureReason": "consentNotGiven",
  "status": "issued",
  "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
  "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
}
GET/projects/{project}/portOuts

List all port outs

Returns a list of port outs.

Preview

This endpoint is currently in preview and might change in the future.

We’re excited to hear your feedback and ideas. Please send an email to support@gigs.com to share your thoughts.

Path Parameters

  • Name
    project
    Type
    string
    required
    Description

    The unique identifier for the project.

    Example: "gigs"

Query Parameters

  • Name
    subscription
    Type
    string
    Description

    The unique identifier of the subscription to be filtered by.

    Example: "sub_0SNlurA049MEWV2gSfSxi00xlPIi"
  • Name
    status
    Type
    array
    Description

    A comma-separated list of statuses to filter the port outs by. Only initiated, processing and issued port outs are returned by default.

    Default: initiated,issued,processing
  • Name
    after
    Type
    string
    Description

    A cursor for use in pagination. The after parameter takes an object ID that defines the position in the list, only items immediately following the item with that ID will be returned.

  • Name
    before
    Type
    string
    Description

    A cursor for use in pagination. The before parameter takes an object ID that defines the position in the list, only items immediately preceding the item with that ID will be returned.

  • Name
    limit
    Type
    integer
    Description

    The limit of items to be returned in the list, between 0 and 200.

    Default: 10
    >= 0
    <= 200

Responses

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

  • Name
    object
    Type
    string
    Description

    Type of object is always list.

    Allowed values: list 
  • Name
    items
    Type
    array
    Description
    List of objects of type `portOut`.
  • Name
    moreItemsAfter
    Type
    nullable string
    Description

    A unique identifier to be used as after pagination parameter if more items are available sorted after the current batch of items.

  • Name
    moreItemsBefore
    Type
    nullable string
    Description

    A unique identifier to be used as before pagination parameter if more items are available sorted before the current batch of items.

Request

GET
/projects/{project}/portOuts
curl https://api.gigs.com/projects/{project}/portOuts \
-X GET \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {token}" \
-H "Accept: application/json"

Response

{
  "object": "list",
  "items": [
    {
      "object": "portOut",
      "id": "pto_0SNlurA049MEWV4DWEaT4SaeDI8s",
      "behavior": "portOut",
      "createdAt": "2020-01-01T00:00:00Z",
      "expiredAt": "2022-02-21T19:38:34Z",
      "failureReason": "consentNotGiven",
      "status": "issued",
      "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
      "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
    }
  ],
  "moreItemsAfter": null,
  "moreItemsBefore": null
}
POST/projects/{project}/portOuts

Create port out

Create a new port out.

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.

Body

  • Name
    behavior
    Type
    nullable string
    Description

    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.

    Example: "portOut"
    Default: portOut
    Allowed values: cancelOnly portOut 
  • Name
    subscription
    Type
    string
    required
    Description

    Unique identifier of the subscription the port out applies to.

    Example: "sub_0SNlurA049MEWV2gSfSxi00xlPIi"

Path Parameters

  • Name
    project
    Type
    string
    required
    Description

    The unique identifier for the project.

    Example: "gigs"

Responses

Returns the created port out.

  • Name
    object
    Type
    string
    Description

    Type of object is always portOut.

    Allowed values: portOut 
  • Name
    id
    Type
    string
    Description

    Unique identifier for the port out.

    Example: "pto_0SNlurA049MEWV4DWEaT4SaeDI8s"
  • Name
    behavior
    Type
    string
    Description

    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.

    Example: "portOut"
    Allowed values: cancelOnly portOut 
  • Name
    createdAt
    Type
    string
    Description

    Time when the port out was created.

    Example: "2020-01-01T00:00:00Z"
  • Name
    expiredAt
    Type
    nullable string
    Description

    Time when the port out expires and won't be valid anymore.

    Example: "2022-02-21T19:38:34Z"
  • Name
    failureReason
    Type
    nullable string
    Description

    The reason for the port out failure.

    Example: "consentNotGiven"
    Allowed values: consentNotGiven consentRequestCanceled 
  • Name
    status
    Type
    string
    Description

    The current status of the port out.

    Example: "issued"
    Allowed values: expired failed initiated issued processing 
  • Name
    subscription
    Type
    string
    Description

    Unique identifier of the subscription affected.

    Example: "sub_0SNlurA049MEWV2gSfSxi00xlPIi"
  • Name
    user
    Type
    string
    Description

    Unique identifier for the user this port out credentials are for.

    Example: "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"

Request

POST
/projects/{project}/portOuts
curl https://api.gigs.com/projects/{project}/portOuts \
-X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {token}" \
-H "Accept: application/json" \
-d "{\"behavior\":\"portOut\",\"subscription\":\"sub_0SNlurA049MEWV2gSfSxi00xlPIi\"}"

Response

{
  "object": "portOut",
  "id": "pto_0SNlurA049MEWV4DWEaT4SaeDI8s",
  "behavior": "portOut",
  "createdAt": "2020-01-01T00:00:00Z",
  "expiredAt": "2022-02-21T19:38:34Z",
  "failureReason": "consentNotGiven",
  "status": "issued",
  "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
  "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
}
GET/projects/{project}/portOuts/{portOut}

Retrieve port out

Retrieves the details of an existing port out.

Preview

This endpoint is currently in preview and might change in the future.

We’re excited to hear your feedback and ideas. Please send an email to support@gigs.com to share your thoughts.

Path Parameters

  • Name
    project
    Type
    string
    required
    Description

    The unique identifier for the project.

    Example: "gigs"
  • Name
    portOut
    Type
    string
    required
    Description

    The unique identifier for the port out.

    Example: "pto_0SNlurA049MEWV4DWEaT4SaeDI8s"

Responses

Returns the port out.

  • Name
    object
    Type
    string
    Description

    Type of object is always portOut.

    Allowed values: portOut 
  • Name
    id
    Type
    string
    Description

    Unique identifier for the port out.

    Example: "pto_0SNlurA049MEWV4DWEaT4SaeDI8s"
  • Name
    behavior
    Type
    string
    Description

    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.

    Example: "portOut"
    Allowed values: cancelOnly portOut 
  • Name
    createdAt
    Type
    string
    Description

    Time when the port out was created.

    Example: "2020-01-01T00:00:00Z"
  • Name
    expiredAt
    Type
    nullable string
    Description

    Time when the port out expires and won't be valid anymore.

    Example: "2022-02-21T19:38:34Z"
  • Name
    failureReason
    Type
    nullable string
    Description

    The reason for the port out failure.

    Example: "consentNotGiven"
    Allowed values: consentNotGiven consentRequestCanceled 
  • Name
    status
    Type
    string
    Description

    The current status of the port out.

    Example: "issued"
    Allowed values: expired failed initiated issued processing 
  • Name
    subscription
    Type
    string
    Description

    Unique identifier of the subscription affected.

    Example: "sub_0SNlurA049MEWV2gSfSxi00xlPIi"
  • Name
    user
    Type
    string
    Description

    Unique identifier for the user this port out credentials are for.

    Example: "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"

Request

GET
/projects/{project}/portOuts/{portOut}
curl https://api.gigs.com/projects/{project}/portOuts/{portOut} \
-X GET \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {token}" \
-H "Accept: application/json"

Response

{
  "object": "portOut",
  "id": "pto_0SNlurA049MEWV4DWEaT4SaeDI8s",
  "behavior": "portOut",
  "createdAt": "2020-01-01T00:00:00Z",
  "expiredAt": "2022-02-21T19:38:34Z",
  "failureReason": "consentNotGiven",
  "status": "issued",
  "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
  "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
}
GET/projects/{project}/portOuts/{portOut}/credentials

Retrieve port out credentials

Retrieve the credentials of an issued port out.

Preview

This endpoint is currently in preview and might change in the future.

We’re excited to hear your feedback and ideas. Please send an email to support@gigs.com to share your thoughts.

Path Parameters

  • Name
    project
    Type
    string
    required
    Description

    The unique identifier for the project.

    Example: "gigs"
  • Name
    portOut
    Type
    string
    required
    Description

    The unique identifier for the port out.

    Example: "pto_0SNlurA049MEWV4DWEaT4SaeDI8s"

Responses

Returns the port out credentials.

  • Name
    object
    Type
    string
    Description

    Type of object is always portOutCredentials.

    Allowed values: portOutCredentials 
  • Name
    accountNumber
    Type
    nullable string
    Description

    The account number on the service provider. Account number is null if no account number is issued in the respective country.

    Example: "123456789"
  • Name
    accountPin
    Type
    string
    Description

    The account pin from the service provider.

    Example: "1234"
  • Name
    portOut
    Type
    string
    Description

    Unique identifier of the port out this credentials are for.

    Example: "pto_0SNlurA049MEWV4DWEaT4SaeDI8s"

Request

GET
/projects/{project}/portOuts/{portOut}/credentials
curl https://api.gigs.com/projects/{project}/portOuts/{portOut}/credentials \
-X GET \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {token}" \
-H "Accept: application/json"

Response

{
  "object": "portOutCredentials",
  "accountNumber": "123456789",
  "accountPin": "1234",
  "portOut": "pto_0SNlurA049MEWV4DWEaT4SaeDI8s"
}
POST/projects/{project}/portOuts/{portOut}/expire

Expire existing port out credentials

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

Preview

This endpoint is currently in preview and might change in the future.

We’re excited to hear your feedback and ideas. Please send an email to support@gigs.com to share your thoughts.

Path Parameters

  • Name
    project
    Type
    string
    required
    Description

    The unique identifier for the project.

    Example: "gigs"
  • Name
    portOut
    Type
    string
    required
    Description

    The unique identifier for the port out.

    Example: "pto_0SNlurA049MEWV4DWEaT4SaeDI8s"

Responses

Returns the port out

  • Name
    object
    Type
    string
    Description

    Type of object is always portOut.

    Allowed values: portOut 
  • Name
    id
    Type
    string
    Description

    Unique identifier for the port out.

    Example: "pto_0SNlurA049MEWV4DWEaT4SaeDI8s"
  • Name
    behavior
    Type
    string
    Description

    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.

    Example: "portOut"
    Allowed values: cancelOnly portOut 
  • Name
    createdAt
    Type
    string
    Description

    Time when the port out was created.

    Example: "2020-01-01T00:00:00Z"
  • Name
    expiredAt
    Type
    nullable string
    Description

    Time when the port out expires and won't be valid anymore.

    Example: "2022-02-21T19:38:34Z"
  • Name
    failureReason
    Type
    nullable string
    Description

    The reason for the port out failure.

    Example: "consentNotGiven"
    Allowed values: consentNotGiven consentRequestCanceled 
  • Name
    status
    Type
    string
    Description

    The current status of the port out.

    Example: "issued"
    Allowed values: expired failed initiated issued processing 
  • Name
    subscription
    Type
    string
    Description

    Unique identifier of the subscription affected.

    Example: "sub_0SNlurA049MEWV2gSfSxi00xlPIi"
  • Name
    user
    Type
    string
    Description

    Unique identifier for the user this port out credentials are for.

    Example: "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"

Request

POST
/projects/{project}/portOuts/{portOut}/expire
curl https://api.gigs.com/projects/{project}/portOuts/{portOut}/expire \
-X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {token}" \
-H "Accept: application/json"

Response

{
  "object": "portOut",
  "id": "pto_0SNlurA049MEWV4DWEaT4SaeDI8s",
  "behavior": "portOut",
  "createdAt": "2020-01-01T00:00:00Z",
  "expiredAt": "2022-02-21T19:38:34Z",
  "failureReason": "consentNotGiven",
  "status": "issued",
  "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
  "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
}