Portings

The Porting resource

Porting is required when a user wants to keep their phone number when changing their subscription. There are multiple steps involved between the user, their previous carrier, and the new subscriber. Visit our how porting works guide for more information.

Properties

  • Name
    object
    Type
    string
    Description

    Type of object is always porting.

  • Name
    id
    Type
    string
    Description

    Unique identifier for the porting.

    Example: prt_0SNlurA049MEWV39s2kSYqaat7ZS
  • Name
    accountNumber
    Type
    nullable string
    Description

    The account number on the donor service provider.

    Example: 123456789
  • Name
    accountPinExists
    Type
    boolean
    Description

    Whether the account PIN has been provided.

    Example: true
  • Name
    address
    Type
    nullable object
    Description
    The address of the account holder on the donor service provider.
  • Name
    birthday
    Type
    nullable string
    Description

    The birthday of the account holder on the donor service provider.

    Example: 2017-07-21
  • Name
    canceledAt
    Type
    nullable string
    Description

    Time when the porting was canceled.

    Example: 2021-01-21T19:39:53Z
  • Name
    completedAt
    Type
    nullable string
    Description

    Time when the porting was completed.

    Example: 2021-01-21T19:36:57Z
  • Name
    createdAt
    Type
    string
    Description

    Time when the porting was created.

    Example: 2021-01-21T19:12:28Z
  • Name
    declinedAttempts
    Type
    integer
    Description

    The number of declined porting attempts so far.

    Example: 0
    >= 0
  • Name
    declinedCode
    Type
    nullable string
    PREVIEW
    Description

    The code reason for the declined porting.

    Example: portingPhoneNumberPortProtected
  • Name
    declinedMessage
    Type
    nullable string
    PREVIEW
    Description

    The reason description for the declined porting.

    Example: The phone number has port protection on the provider.
  • Name
    donorProvider
    Type
    nullable object
    Description
    The service provider from whom the number is ported.
  • Name
    donorProviderApproval
    Type
    nullable boolean
    Description

    Whether the donor provider has approved or not the porting.

    Example: true
  • Name
    expiredAt
    Type
    nullable string
    Description

    Time when the porting was expired.

    Example: 2021-01-21T19:39:53Z
  • Name
    firstName
    Type
    nullable string
    Description

    The first name of the account holder on the donor service provider.

    Example: Jerry
  • Name
    lastDeclinedAt
    Type
    nullable string
    Description

    Time when the porting was last declined.

    Example: 2021-01-21T19:31:13Z
  • Name
    lastName
    Type
    nullable string
    Description

    The last name of the account holder on the donor service provider.

    Example: Seinfeld
  • Name
    lastRequestedAt
    Type
    nullable string
    Description

    Time when the porting was last requested.

    Example: 2021-01-21T19:22:31Z
  • Name
    phoneNumber
    Type
    string
    Description

    The phone number to port in E.164 format.

    Example: +19591234567
  • Name
    provider
    Type
    string
    Description

    The ID of the recipient network provider.

    Example: p9
  • Name
    recipientProvider
    Type
    object
    Description
    The service provider to whom the number is ported.
  • Name
    required
    Type
    array
    Description

    List of fields required for the porting to be processable. The fields depend on the donor and recipient providers.

    Example: accountNumber,accountPin,address,birthday,donorProvider,donorProviderApproval,firstName,lastName
  • Name
    status
    Type
    string
    Description

    The current status of the porting.

    Allowed values: draft, pending, informationRequired, requested, declined, completed, canceled, expired
  • Name
    subscription
    Type
    nullable string
    Description

    Unique identifier for the porting subscription.

    Example: sub_0SNlurA049MEWV2gSfSxi00xlPIi
  • Name
    user
    Type
    string
    Description

    Unique identifier for the user this porting is for.

    Example: usr_0SNlurA049MEWV4OpCwsNyC9Kn2d

Response

{
  "object": "porting",
  "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS",
  "accountNumber": "123456789",
  "accountPinExists": true,
  "address": {
    "city": "New York City",
    "country": "US",
    "line1": "129 West 81st Street",
    "line2": "Apartment 5A",
    "postalCode": "10024",
    "state": "NY"
  },
  "birthday": "2017-07-21",
  "canceledAt": "2021-01-21T19:39:53Z",
  "completedAt": "2021-01-21T19:36:57Z",
  "createdAt": "2021-01-21T19:12:28Z",
  "declinedCode": "portingPhoneNumberPortProtected",
  "declinedMessage": "The phone number has port protection on the provider.",
  "donorProvider": {
    "object": "serviceProvider",
    "id": "svp_0SNlurA01K6GY5L0XJffY8",
    "name": "AT&T"
  },
  "donorProviderApproval": true,
  "expiredAt": "2021-01-21T19:39:53Z",
  "firstName": "Jerry",
  "lastDeclinedAt": "2021-01-21T19:31:13Z",
  "lastName": "Seinfeld",
  "lastRequestedAt": "2021-01-21T19:22:31Z",
  "phoneNumber": "+19591234567",
  "provider": "p9",
  "recipientProvider": {
    "object": "serviceProvider",
    "id": "svp_0SNlurA01K6GY5L0XJffY8",
    "name": "AT&T"
  },
  "required": [
    "accountNumber",
    "accountPin",
    "address",
    "birthday",
    "donorProvider",
    "donorProviderApproval",
    "firstName",
    "lastName"
  ],
  "status": "draft",
  "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
  "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
}

POST/projects/{project}/portings/{porting}/cancel

Cancel a porting

Cancels a porting. Only portings that have not yet been completed and are not currently being processed can be canceled.

Canceling a porting will result in the activation of the subscription with a new number. To cancel the whole process, end the subscription instead.

Path Parameters

  • Name
    project
    Type
    string
    required
    Description

    The unique identifier for the project.

    Example: gigs
  • Name
    porting
    Type
    string
    required
    Description

    The unique identifier for the porting.

    Example: prt_0SNlurA049MEWV39s2kSYqaat7ZS

Response Schemas

  • Name
    object
    Type
    string
    required
    Description

    Type of object is always porting.

  • Name
    id
    Type
    string
    required
    Description

    Unique identifier for the porting.

    Example: prt_0SNlurA049MEWV39s2kSYqaat7ZS
  • Name
    accountNumber
    Type
    nullable string
    required
    Description

    The account number on the donor service provider.

    Example: 123456789
  • Name
    accountPinExists
    Type
    boolean
    required
    Description

    Whether the account PIN has been provided.

    Example: true
  • Name
    address
    Type
    nullable object
    required
    Description
    The address of the account holder on the donor service provider.
  • Name
    birthday
    Type
    nullable string
    required
    Description

    The birthday of the account holder on the donor service provider.

    Example: 2017-07-21
  • Name
    canceledAt
    Type
    nullable string
    required
    Description

    Time when the porting was canceled.

    Example: 2021-01-21T19:39:53Z
  • Name
    completedAt
    Type
    nullable string
    required
    Description

    Time when the porting was completed.

    Example: 2021-01-21T19:36:57Z
  • Name
    createdAt
    Type
    string
    required
    Description

    Time when the porting was created.

    Example: 2021-01-21T19:12:28Z
  • Name
    declinedAttempts
    Type
    integer
    required
    Description

    The number of declined porting attempts so far.

    Example: 0
    >= 0
  • Name
    declinedCode
    Type
    nullable string
    PREVIEW
    required
    Description

    The code reason for the declined porting.

    Example: portingPhoneNumberPortProtected
  • Name
    declinedMessage
    Type
    nullable string
    PREVIEW
    required
    Description

    The reason description for the declined porting.

    Example: The phone number has port protection on the provider.
  • Name
    donorProvider
    Type
    nullable object
    required
    Description
    The service provider from whom the number is ported.
  • Name
    donorProviderApproval
    Type
    nullable boolean
    required
    Description

    Whether the donor provider has approved or not the porting.

    Example: true
  • Name
    expiredAt
    Type
    nullable string
    required
    Description

    Time when the porting was expired.

    Example: 2021-01-21T19:39:53Z
  • Name
    firstName
    Type
    nullable string
    required
    Description

    The first name of the account holder on the donor service provider.

    Example: Jerry
  • Name
    lastDeclinedAt
    Type
    nullable string
    required
    Description

    Time when the porting was last declined.

    Example: 2021-01-21T19:31:13Z
  • Name
    lastName
    Type
    nullable string
    required
    Description

    The last name of the account holder on the donor service provider.

    Example: Seinfeld
  • Name
    lastRequestedAt
    Type
    nullable string
    required
    Description

    Time when the porting was last requested.

    Example: 2021-01-21T19:22:31Z
  • Name
    phoneNumber
    Type
    string
    required
    Description

    The phone number to port in E.164 format.

    Example: +19591234567
  • Name
    provider
    Type
    string
    required
    Description

    The ID of the recipient network provider.

    Example: p9
  • Name
    recipientProvider
    Type
    object
    required
    Description
    The service provider to whom the number is ported.
  • Name
    required
    Type
    array
    required
    Description

    List of fields required for the porting to be processable. The fields depend on the donor and recipient providers.

    Example: accountNumber,accountPin,address,birthday,donorProvider,donorProviderApproval,firstName,lastName
  • Name
    status
    Type
    string
    required
    Description

    The current status of the porting.

    Allowed values: draft, pending, informationRequired, requested, declined, completed, canceled, expired
  • Name
    subscription
    Type
    nullable string
    required
    Description

    Unique identifier for the porting subscription.

    Example: sub_0SNlurA049MEWV2gSfSxi00xlPIi
  • Name
    user
    Type
    string
    required
    Description

    Unique identifier for the user this porting is for.

    Example: usr_0SNlurA049MEWV4OpCwsNyC9Kn2d

Request

POST
/projects/{project}/portings/{porting}/cancel
curl https://api.gigs.com/projects/{project}/portings/{porting}/cancel \
-X POST \
-H "Content-type: application/json" \
-H "Authorization: Bearer {token}" \
-H "Accept: application/json"

Response

{
  "object": "porting",
  "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS",
  "accountNumber": "123456789",
  "accountPinExists": true,
  "address": {
    "city": "New York City",
    "country": "US",
    "line1": "129 West 81st Street",
    "line2": "Apartment 5A",
    "postalCode": "10024",
    "state": "NY"
  },
  "birthday": "2017-07-21",
  "canceledAt": "2021-01-21T19:39:53Z",
  "completedAt": "2021-01-21T19:36:57Z",
  "createdAt": "2021-01-21T19:12:28Z",
  "declinedAttempts": 0,
  "declinedCode": "portingPhoneNumberPortProtected",
  "declinedMessage": "The phone number has port protection on the provider.",
  "donorProvider": {
    "object": "serviceProvider",
    "id": "svp_0SNlurA01K6GY5L0XJffY8",
    "name": "AT&T",
    "recipientProviders": [
      "p3"
    ]
  },
  "donorProviderApproval": true,
  "expiredAt": "2021-01-21T19:39:53Z",
  "firstName": "Jerry",
  "lastDeclinedAt": "2021-01-21T19:31:13Z",
  "lastName": "Seinfeld",
  "lastRequestedAt": "2021-01-21T19:22:31Z",
  "phoneNumber": "+19591234567",
  "provider": "p9",
  "recipientProvider": {
    "object": "serviceProvider",
    "id": "svp_0SNlurA01K6GY5L0XJffY8",
    "name": "AT&T",
    "recipientProviders": [
      "p3"
    ]
  },
  "required": [
    "accountNumber",
    "accountPin",
    "address",
    "birthday",
    "donorProvider",
    "donorProviderApproval",
    "firstName",
    "lastName"
  ],
  "status": "draft",
  "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
  "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
}

GET/projects/{project}/portings/{porting}

Retrieve a Porting

Retrieves the details of an existing porting.

Path Parameters

  • Name
    project
    Type
    string
    required
    Description

    The unique identifier for the project.

    Example: gigs
  • Name
    porting
    Type
    string
    required
    Description

    The unique identifier for the porting.

    Example: prt_0SNlurA049MEWV39s2kSYqaat7ZS

Response Schemas

  • Name
    object
    Type
    string
    required
    Description

    Type of object is always porting.

  • Name
    id
    Type
    string
    required
    Description

    Unique identifier for the porting.

    Example: prt_0SNlurA049MEWV39s2kSYqaat7ZS
  • Name
    accountNumber
    Type
    nullable string
    required
    Description

    The account number on the donor service provider.

    Example: 123456789
  • Name
    accountPinExists
    Type
    boolean
    required
    Description

    Whether the account PIN has been provided.

    Example: true
  • Name
    address
    Type
    nullable object
    required
    Description
    The address of the account holder on the donor service provider.
  • Name
    birthday
    Type
    nullable string
    required
    Description

    The birthday of the account holder on the donor service provider.

    Example: 2017-07-21
  • Name
    canceledAt
    Type
    nullable string
    required
    Description

    Time when the porting was canceled.

    Example: 2021-01-21T19:39:53Z
  • Name
    completedAt
    Type
    nullable string
    required
    Description

    Time when the porting was completed.

    Example: 2021-01-21T19:36:57Z
  • Name
    createdAt
    Type
    string
    required
    Description

    Time when the porting was created.

    Example: 2021-01-21T19:12:28Z
  • Name
    declinedAttempts
    Type
    integer
    required
    Description

    The number of declined porting attempts so far.

    Example: 0
    >= 0
  • Name
    declinedCode
    Type
    nullable string
    PREVIEW
    required
    Description

    The code reason for the declined porting.

    Example: portingPhoneNumberPortProtected
  • Name
    declinedMessage
    Type
    nullable string
    PREVIEW
    required
    Description

    The reason description for the declined porting.

    Example: The phone number has port protection on the provider.
  • Name
    donorProvider
    Type
    nullable object
    required
    Description
    The service provider from whom the number is ported.
  • Name
    donorProviderApproval
    Type
    nullable boolean
    required
    Description

    Whether the donor provider has approved or not the porting.

    Example: true
  • Name
    expiredAt
    Type
    nullable string
    required
    Description

    Time when the porting was expired.

    Example: 2021-01-21T19:39:53Z
  • Name
    firstName
    Type
    nullable string
    required
    Description

    The first name of the account holder on the donor service provider.

    Example: Jerry
  • Name
    lastDeclinedAt
    Type
    nullable string
    required
    Description

    Time when the porting was last declined.

    Example: 2021-01-21T19:31:13Z
  • Name
    lastName
    Type
    nullable string
    required
    Description

    The last name of the account holder on the donor service provider.

    Example: Seinfeld
  • Name
    lastRequestedAt
    Type
    nullable string
    required
    Description

    Time when the porting was last requested.

    Example: 2021-01-21T19:22:31Z
  • Name
    phoneNumber
    Type
    string
    required
    Description

    The phone number to port in E.164 format.

    Example: +19591234567
  • Name
    provider
    Type
    string
    required
    Description

    The ID of the recipient network provider.

    Example: p9
  • Name
    recipientProvider
    Type
    object
    required
    Description
    The service provider to whom the number is ported.
  • Name
    required
    Type
    array
    required
    Description

    List of fields required for the porting to be processable. The fields depend on the donor and recipient providers.

    Example: accountNumber,accountPin,address,birthday,donorProvider,donorProviderApproval,firstName,lastName
  • Name
    status
    Type
    string
    required
    Description

    The current status of the porting.

    Allowed values: draft, pending, informationRequired, requested, declined, completed, canceled, expired
  • Name
    subscription
    Type
    nullable string
    required
    Description

    Unique identifier for the porting subscription.

    Example: sub_0SNlurA049MEWV2gSfSxi00xlPIi
  • Name
    user
    Type
    string
    required
    Description

    Unique identifier for the user this porting is for.

    Example: usr_0SNlurA049MEWV4OpCwsNyC9Kn2d

Request

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

Response

{
  "object": "porting",
  "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS",
  "accountNumber": "123456789",
  "accountPinExists": true,
  "address": {
    "city": "New York City",
    "country": "US",
    "line1": "129 West 81st Street",
    "line2": "Apartment 5A",
    "postalCode": "10024",
    "state": "NY"
  },
  "birthday": "2017-07-21",
  "canceledAt": "2021-01-21T19:39:53Z",
  "completedAt": "2021-01-21T19:36:57Z",
  "createdAt": "2021-01-21T19:12:28Z",
  "declinedAttempts": 0,
  "declinedCode": "portingPhoneNumberPortProtected",
  "declinedMessage": "The phone number has port protection on the provider.",
  "donorProvider": {
    "object": "serviceProvider",
    "id": "svp_0SNlurA01K6GY5L0XJffY8",
    "name": "AT&T",
    "recipientProviders": [
      "p3"
    ]
  },
  "donorProviderApproval": true,
  "expiredAt": "2021-01-21T19:39:53Z",
  "firstName": "Jerry",
  "lastDeclinedAt": "2021-01-21T19:31:13Z",
  "lastName": "Seinfeld",
  "lastRequestedAt": "2021-01-21T19:22:31Z",
  "phoneNumber": "+19591234567",
  "provider": "p9",
  "recipientProvider": {
    "object": "serviceProvider",
    "id": "svp_0SNlurA01K6GY5L0XJffY8",
    "name": "AT&T",
    "recipientProviders": [
      "p3"
    ]
  },
  "required": [
    "accountNumber",
    "accountPin",
    "address",
    "birthday",
    "donorProvider",
    "donorProviderApproval",
    "firstName",
    "lastName"
  ],
  "status": "draft",
  "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
  "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
}

PATCH/projects/{project}/portings/{porting}

Update a porting

Updates a porting with the given parameters.

Depending on the status of the porting, some fields may not be updated anymore. When all the required information is provided, the porting will be requested. If the porting is declined, it will be retried. To retry a porting without providing any new information, simply update the porting with an empty request.

Related guide: How Porting Works

Body

  • Name
    accountNumber
    Type
    string
    Description

    The account number on the donor service provider.

    Example: 123456789
  • Name
    accountPin
    Type
    string
    Description

    The pin for the account on the donor service provider. This will be used only for the porting.

    Example: 1234
  • Name
    address
    Type
    nullable object
    Description
    The address of the account holder on the donor service provider.
  • Name
    birthday
    Type
    string
    Description

    The birthday of the account holder on the donor service provider.

    Example: 2017-07-21
  • Name
    donorProvider
    Type
    string
    Description

    The unique identifier of the donor service provider.

    Example: svp_0SNlurA01K6GY5L0XJffY8
  • Name
    donorProviderApproval
    Type
    nullable boolean
    Description

    Whether the donor provider has approved or not the porting.

    Example: true
  • Name
    firstName
    Type
    string
    Description

    The first name of the account holder.

    Example: Jerry
  • Name
    lastName
    Type
    string
    Description

    The last name of the account holder.

    Example: Seinfeld
  • Name
    phoneNumber
    Type
    string
    Description

    The phone number to port in E.164 format. This is only updatable when the porting is in a status of: draft

    Example: +19591234567
  • Name
    provider
    Type
    string
    Description

    The ID of the recipient network provider. This is only updatable when the porting is in a status of: draft

    Example: p9

Path Parameters

  • Name
    project
    Type
    string
    required
    Description

    The unique identifier for the project.

    Example: gigs
  • Name
    porting
    Type
    string
    required
    Description

    The unique identifier for the porting.

    Example: prt_0SNlurA049MEWV39s2kSYqaat7ZS

Response Schemas

  • Name
    object
    Type
    string
    required
    Description

    Type of object is always porting.

  • Name
    id
    Type
    string
    required
    Description

    Unique identifier for the porting.

    Example: prt_0SNlurA049MEWV39s2kSYqaat7ZS
  • Name
    accountNumber
    Type
    nullable string
    required
    Description

    The account number on the donor service provider.

    Example: 123456789
  • Name
    accountPinExists
    Type
    boolean
    required
    Description

    Whether the account PIN has been provided.

    Example: true
  • Name
    address
    Type
    nullable object
    required
    Description
    The address of the account holder on the donor service provider.
  • Name
    birthday
    Type
    nullable string
    required
    Description

    The birthday of the account holder on the donor service provider.

    Example: 2017-07-21
  • Name
    canceledAt
    Type
    nullable string
    required
    Description

    Time when the porting was canceled.

    Example: 2021-01-21T19:39:53Z
  • Name
    completedAt
    Type
    nullable string
    required
    Description

    Time when the porting was completed.

    Example: 2021-01-21T19:36:57Z
  • Name
    createdAt
    Type
    string
    required
    Description

    Time when the porting was created.

    Example: 2021-01-21T19:12:28Z
  • Name
    declinedAttempts
    Type
    integer
    required
    Description

    The number of declined porting attempts so far.

    Example: 0
    >= 0
  • Name
    declinedCode
    Type
    nullable string
    PREVIEW
    required
    Description

    The code reason for the declined porting.

    Example: portingPhoneNumberPortProtected
  • Name
    declinedMessage
    Type
    nullable string
    PREVIEW
    required
    Description

    The reason description for the declined porting.

    Example: The phone number has port protection on the provider.
  • Name
    donorProvider
    Type
    nullable object
    required
    Description
    The service provider from whom the number is ported.
  • Name
    donorProviderApproval
    Type
    nullable boolean
    required
    Description

    Whether the donor provider has approved or not the porting.

    Example: true
  • Name
    expiredAt
    Type
    nullable string
    required
    Description

    Time when the porting was expired.

    Example: 2021-01-21T19:39:53Z
  • Name
    firstName
    Type
    nullable string
    required
    Description

    The first name of the account holder on the donor service provider.

    Example: Jerry
  • Name
    lastDeclinedAt
    Type
    nullable string
    required
    Description

    Time when the porting was last declined.

    Example: 2021-01-21T19:31:13Z
  • Name
    lastName
    Type
    nullable string
    required
    Description

    The last name of the account holder on the donor service provider.

    Example: Seinfeld
  • Name
    lastRequestedAt
    Type
    nullable string
    required
    Description

    Time when the porting was last requested.

    Example: 2021-01-21T19:22:31Z
  • Name
    phoneNumber
    Type
    string
    required
    Description

    The phone number to port in E.164 format.

    Example: +19591234567
  • Name
    provider
    Type
    string
    required
    Description

    The ID of the recipient network provider.

    Example: p9
  • Name
    recipientProvider
    Type
    object
    required
    Description
    The service provider to whom the number is ported.
  • Name
    required
    Type
    array
    required
    Description

    List of fields required for the porting to be processable. The fields depend on the donor and recipient providers.

    Example: accountNumber,accountPin,address,birthday,donorProvider,donorProviderApproval,firstName,lastName
  • Name
    status
    Type
    string
    required
    Description

    The current status of the porting.

    Allowed values: draft, pending, informationRequired, requested, declined, completed, canceled, expired
  • Name
    subscription
    Type
    nullable string
    required
    Description

    Unique identifier for the porting subscription.

    Example: sub_0SNlurA049MEWV2gSfSxi00xlPIi
  • Name
    user
    Type
    string
    required
    Description

    Unique identifier for the user this porting is for.

    Example: usr_0SNlurA049MEWV4OpCwsNyC9Kn2d

Request

PATCH
/projects/{project}/portings/{porting}
curl https://api.gigs.com/projects/{project}/portings/{porting} \
-X PATCH \
-H "Content-type: application/json" \
-H "Authorization: Bearer {token}" \
-H "Accept: application/json" \
-d "{\"accountNumber\":\"123456789\",\"accountPin\":\"1234\",\"address\":{\"city\":\"New York City\",\"country\":\"US\",\"line1\":\"129 West 81st Street\",\"line2\":\"Apartment 5A\",\"postalCode\":\"10024\",\"state\":\"NY\"},\"birthday\":\"2017-07-21\",\"donorProvider\":\"svp_0SNlurA01K6GY5L0XJffY8\",\"donorProviderApproval\":true,\"firstName\":\"Jerry\",\"lastName\":\"Seinfeld\",\"phoneNumber\":\"+19591234567\",\"provider\":\"p9\"}"

Response

{
  "object": "porting",
  "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS",
  "accountNumber": "123456789",
  "accountPinExists": true,
  "address": {
    "city": "New York City",
    "country": "US",
    "line1": "129 West 81st Street",
    "line2": "Apartment 5A",
    "postalCode": "10024",
    "state": "NY"
  },
  "birthday": "2017-07-21",
  "canceledAt": "2021-01-21T19:39:53Z",
  "completedAt": "2021-01-21T19:36:57Z",
  "createdAt": "2021-01-21T19:12:28Z",
  "declinedAttempts": 0,
  "declinedCode": "portingPhoneNumberPortProtected",
  "declinedMessage": "The phone number has port protection on the provider.",
  "donorProvider": {
    "object": "serviceProvider",
    "id": "svp_0SNlurA01K6GY5L0XJffY8",
    "name": "AT&T",
    "recipientProviders": [
      "p3"
    ]
  },
  "donorProviderApproval": true,
  "expiredAt": "2021-01-21T19:39:53Z",
  "firstName": "Jerry",
  "lastDeclinedAt": "2021-01-21T19:31:13Z",
  "lastName": "Seinfeld",
  "lastRequestedAt": "2021-01-21T19:22:31Z",
  "phoneNumber": "+19591234567",
  "provider": "p9",
  "recipientProvider": {
    "object": "serviceProvider",
    "id": "svp_0SNlurA01K6GY5L0XJffY8",
    "name": "AT&T",
    "recipientProviders": [
      "p3"
    ]
  },
  "required": [
    "accountNumber",
    "accountPin",
    "address",
    "birthday",
    "donorProvider",
    "donorProviderApproval",
    "firstName",
    "lastName"
  ],
  "status": "draft",
  "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
  "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
}

GET/projects/{project}/portings

List all portings

Returns a list of portings. The portings returned are sorted by creation date, with the most recently created portings appearing first.

Path Parameters

  • Name
    project
    Type
    string
    required
    Description

    The unique identifier for the project.

    Example: gigs

Query Parameters

  • Name
    status
    Type
    array
    Description

    The status to filter the portings by.

  • Name
    subscription
    Type
    string
    Description

    The unique identifier of the subscription to be filtered by.

    Example: sub_0SNlurA049MEWV2gSfSxi00xlPIi
  • Name
    after
    Type
    string
    Description

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

  • Name
    before
    Type
    string
    Description

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

  • Name
    limit
    Type
    integer
    Description

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

    Default: 10
    >= 0
    <= 200

Response Schemas

  • Name
    object
    Type
    string
    required
    Description

    Type of object is always list.

  • Name
    items
    Type
    array
    required
    Description
    List of objects of type `porting`.
  • Name
    moreItemsAfter
    Type
    nullable string
    required
    Description

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

  • Name
    moreItemsBefore
    Type
    nullable string
    required
    Description

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

Request

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

Response

{
  "object": "list",
  "items": [
    {
      "object": "porting",
      "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS",
      "accountNumber": "123456789",
      "accountPinExists": true,
      "address": {
        "city": "New York City",
        "country": "US",
        "line1": "129 West 81st Street",
        "line2": "Apartment 5A",
        "postalCode": "10024",
        "state": "NY"
      },
      "birthday": "2017-07-21",
      "canceledAt": "2021-01-21T19:39:53Z",
      "completedAt": "2021-01-21T19:36:57Z",
      "createdAt": "2021-01-21T19:12:28Z",
      "declinedAttempts": 0,
      "declinedCode": "portingPhoneNumberPortProtected",
      "declinedMessage": "The phone number has port protection on the provider.",
      "donorProvider": {
        "object": "serviceProvider",
        "id": "svp_0SNlurA01K6GY5L0XJffY8",
        "name": "AT&T",
        "recipientProviders": [
          "p3"
        ]
      },
      "donorProviderApproval": true,
      "expiredAt": "2021-01-21T19:39:53Z",
      "firstName": "Jerry",
      "lastDeclinedAt": "2021-01-21T19:31:13Z",
      "lastName": "Seinfeld",
      "lastRequestedAt": "2021-01-21T19:22:31Z",
      "phoneNumber": "+19591234567",
      "provider": "p9",
      "recipientProvider": {
        "object": "serviceProvider",
        "id": "svp_0SNlurA01K6GY5L0XJffY8",
        "name": "AT&T",
        "recipientProviders": [
          "p3"
        ]
      },
      "required": [
        "accountNumber",
        "accountPin",
        "address",
        "birthday",
        "donorProvider",
        "donorProviderApproval",
        "firstName",
        "lastName"
      ],
      "status": "draft",
      "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
      "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
    }
  ],
  "moreItemsAfter": null,
  "moreItemsBefore": null
}

POST/projects/{project}/portings

Create a porting

Creates a new porting. It will be created in draft status and can be later used to create an order or subscription for the same provider.

Only some of the fields are required during creation. Some providers require additional fields which are listed in the required array property of the porting. It will remain in informationRequired status and will not be requested until all required information has been collected.

Related guide: How Porting Works

Body

  • Name
    accountNumber
    Type
    nullable string
    Description

    The account number on the donor service provider.

    Example: 123456789
  • Name
    accountPin
    Type
    nullable string
    Description

    The pin for the account on the donor service provider. This will be used only for the porting.

    Example: 1234
  • Name
    address
    Type
    nullable object
    Description
    The address of the account holder on the donor service provider.
  • Name
    birthday
    Type
    nullable string
    Description

    The birthday of the account holder on the donor service provider.

    Example: 2017-07-21
  • Name
    donorProvider
    Type
    nullable string
    Description

    The unique identifier of the donor service provider.

    Example: svp_0SNlurA01K6GY5L0XJffY8
  • Name
    donorProviderApproval
    Type
    nullable boolean
    Description

    Whether the donor provider has approved or not the porting.

    Example: true
  • Name
    firstName
    Type
    nullable string
    Description

    The first name of the account holder.

    Example: Jerry
  • Name
    lastName
    Type
    nullable string
    Description

    The last name of the account holder.

    Example: Seinfeld
  • Name
    phoneNumber
    Type
    string
    required
    Description

    The phone number to port in E.164 format.

    Example: +19591234567
  • Name
    provider
    Type
    string
    required
    Description

    The name of the receiving network provider.

    Example: p9
  • Name
    user
    Type
    string
    required
    Description

    The unique identifier for an existing user the porting should be created for.

    Example: usr_0SNlurA049MEWV4OpCwsNyC9Kn2d

Path Parameters

  • Name
    project
    Type
    string
    required
    Description

    The unique identifier for the project.

    Example: gigs

Response Schemas

  • Name
    object
    Type
    string
    required
    Description

    Type of object is always porting.

  • Name
    id
    Type
    string
    required
    Description

    Unique identifier for the porting.

    Example: prt_0SNlurA049MEWV39s2kSYqaat7ZS
  • Name
    accountNumber
    Type
    nullable string
    required
    Description

    The account number on the donor service provider.

    Example: 123456789
  • Name
    accountPinExists
    Type
    boolean
    required
    Description

    Whether the account PIN has been provided.

    Example: true
  • Name
    address
    Type
    nullable object
    required
    Description
    The address of the account holder on the donor service provider.
  • Name
    birthday
    Type
    nullable string
    required
    Description

    The birthday of the account holder on the donor service provider.

    Example: 2017-07-21
  • Name
    canceledAt
    Type
    nullable string
    required
    Description

    Time when the porting was canceled.

    Example: 2021-01-21T19:39:53Z
  • Name
    completedAt
    Type
    nullable string
    required
    Description

    Time when the porting was completed.

    Example: 2021-01-21T19:36:57Z
  • Name
    createdAt
    Type
    string
    required
    Description

    Time when the porting was created.

    Example: 2021-01-21T19:12:28Z
  • Name
    declinedAttempts
    Type
    integer
    required
    Description

    The number of declined porting attempts so far.

    Example: 0
    >= 0
  • Name
    declinedCode
    Type
    nullable string
    PREVIEW
    required
    Description

    The code reason for the declined porting.

    Example: portingPhoneNumberPortProtected
  • Name
    declinedMessage
    Type
    nullable string
    PREVIEW
    required
    Description

    The reason description for the declined porting.

    Example: The phone number has port protection on the provider.
  • Name
    donorProvider
    Type
    nullable object
    required
    Description
    The service provider from whom the number is ported.
  • Name
    donorProviderApproval
    Type
    nullable boolean
    required
    Description

    Whether the donor provider has approved or not the porting.

    Example: true
  • Name
    expiredAt
    Type
    nullable string
    required
    Description

    Time when the porting was expired.

    Example: 2021-01-21T19:39:53Z
  • Name
    firstName
    Type
    nullable string
    required
    Description

    The first name of the account holder on the donor service provider.

    Example: Jerry
  • Name
    lastDeclinedAt
    Type
    nullable string
    required
    Description

    Time when the porting was last declined.

    Example: 2021-01-21T19:31:13Z
  • Name
    lastName
    Type
    nullable string
    required
    Description

    The last name of the account holder on the donor service provider.

    Example: Seinfeld
  • Name
    lastRequestedAt
    Type
    nullable string
    required
    Description

    Time when the porting was last requested.

    Example: 2021-01-21T19:22:31Z
  • Name
    phoneNumber
    Type
    string
    required
    Description

    The phone number to port in E.164 format.

    Example: +19591234567
  • Name
    provider
    Type
    string
    required
    Description

    The ID of the recipient network provider.

    Example: p9
  • Name
    recipientProvider
    Type
    object
    required
    Description
    The service provider to whom the number is ported.
  • Name
    required
    Type
    array
    required
    Description

    List of fields required for the porting to be processable. The fields depend on the donor and recipient providers.

    Example: accountNumber,accountPin,address,birthday,donorProvider,donorProviderApproval,firstName,lastName
  • Name
    status
    Type
    string
    required
    Description

    The current status of the porting.

    Allowed values: draft, pending, informationRequired, requested, declined, completed, canceled, expired
  • Name
    subscription
    Type
    nullable string
    required
    Description

    Unique identifier for the porting subscription.

    Example: sub_0SNlurA049MEWV2gSfSxi00xlPIi
  • Name
    user
    Type
    string
    required
    Description

    Unique identifier for the user this porting is for.

    Example: usr_0SNlurA049MEWV4OpCwsNyC9Kn2d

Request

POST
/projects/{project}/portings
curl https://api.gigs.com/projects/{project}/portings \
-X POST \
-H "Content-type: application/json" \
-H "Authorization: Bearer {token}" \
-H "Accept: application/json" \
-d "{\"accountNumber\":\"123456789\",\"accountPin\":\"1234\",\"address\":{\"city\":\"New York City\",\"country\":\"US\",\"line1\":\"129 West 81st Street\",\"line2\":\"Apartment 5A\",\"postalCode\":\"10024\",\"state\":\"NY\"},\"birthday\":\"2017-07-21\",\"donorProvider\":\"svp_0SNlurA01K6GY5L0XJffY8\",\"donorProviderApproval\":true,\"firstName\":\"Jerry\",\"lastName\":\"Seinfeld\",\"phoneNumber\":\"+19591234567\",\"provider\":\"p9\",\"user\":\"usr_0SNlurA049MEWV4OpCwsNyC9Kn2d\"}"

Response

{
  "object": "porting",
  "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS",
  "accountNumber": "123456789",
  "accountPinExists": true,
  "address": {
    "city": "New York City",
    "country": "US",
    "line1": "129 West 81st Street",
    "line2": "Apartment 5A",
    "postalCode": "10024",
    "state": "NY"
  },
  "birthday": "2017-07-21",
  "canceledAt": "2021-01-21T19:39:53Z",
  "completedAt": "2021-01-21T19:36:57Z",
  "createdAt": "2021-01-21T19:12:28Z",
  "declinedAttempts": 0,
  "declinedCode": "portingPhoneNumberPortProtected",
  "declinedMessage": "The phone number has port protection on the provider.",
  "donorProvider": {
    "object": "serviceProvider",
    "id": "svp_0SNlurA01K6GY5L0XJffY8",
    "name": "AT&T",
    "recipientProviders": [
      "p3"
    ]
  },
  "donorProviderApproval": true,
  "expiredAt": "2021-01-21T19:39:53Z",
  "firstName": "Jerry",
  "lastDeclinedAt": "2021-01-21T19:31:13Z",
  "lastName": "Seinfeld",
  "lastRequestedAt": "2021-01-21T19:22:31Z",
  "phoneNumber": "+19591234567",
  "provider": "p9",
  "recipientProvider": {
    "object": "serviceProvider",
    "id": "svp_0SNlurA01K6GY5L0XJffY8",
    "name": "AT&T",
    "recipientProviders": [
      "p3"
    ]
  },
  "required": [
    "accountNumber",
    "accountPin",
    "address",
    "birthday",
    "donorProvider",
    "donorProviderApproval",
    "firstName",
    "lastName"
  ],
  "status": "draft",
  "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
  "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
}

GET/serviceProviders/{serviceProvider}

Retrieve a service provider

Retrieves the details of a service provider.

Path Parameters

  • Name
    serviceProvider
    Type
    string
    required
    Description

    The unique identifier for the service provider.

    Example: svp_0SNlurA01K6GY5L0XJffY8

Response Schemas

  • Name
    object
    Type
    string
    required
    Description

    Type of object is always serviceProvider.

  • Name
    id
    Type
    string
    required
    Description

    Unique identifier for the service provider.

    Example: svp_0SNlurA01K6GY5L0XJffY8
  • Name
    name
    Type
    string
    required
    Description

    The name of the service provider, usually a brand name.

    Example: AT&T
  • Name
    recipientProviders
    Type
    array
    required
    Description

    List of network providers IDs that can receive portings from the service provider.

    Default: p3

Request

GET
/serviceProviders/{serviceProvider}
curl https://api.gigs.com/serviceProviders/{serviceProvider} \
-X GET \
-H "Content-type: application/json" \
-H "Authorization: Bearer {token}" \
-H "Accept: application/json"

Response

{
  "object": "serviceProvider",
  "id": "svp_0SNlurA01K6GY5L0XJffY8",
  "name": "AT&T",
  "recipientProviders": [
    "p3"
  ]
}

GET/serviceProviders

List all service providers

Returns a list of service providers.

Query Parameters

  • Name
    recipientProvider
    Type
    string
    Description

    Only return service providers that have the given network provider as supported porting recipient.

    Example: p7

Response Schemas

  • Name
    object
    Type
    string
    required
    Description

    Type of object is always list.

  • Name
    items
    Type
    array
    required
    Description
    List of objects of type `serviceProvider`.
  • Name
    moreItemsAfter
    Type
    nullable string
    required
    Description

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

  • Name
    moreItemsBefore
    Type
    nullable string
    required
    Description

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

Request

GET
/serviceProviders
curl https://api.gigs.com/serviceProviders \
-X GET \
-H "Content-type: application/json" \
-H "Authorization: Bearer {token}" \
-H "Accept: application/json"

Response

{
  "object": "list",
  "items": [
    {
      "object": "serviceProvider",
      "id": "svp_0SNlurA01K6GY5L0XJffY8",
      "name": "AT&T",
      "recipientProviders": [
        "p3"
      ]
    }
  ],
  "moreItemsAfter": null,
  "moreItemsBefore": null
}