Edit a porting order

PATCH 
/porting_orders/:id

Edits the details of an existing porting order.

Any or all of a porting orders attributes may be included in the resource object included in a PATCH request.

If a request does not include all of the attributes for a resource, the system will interpret the missing attributes as if they were included with their current values. To explicitly set something to null, it must be included in the request with a null value.

Path Parameters

id uuidrequired

Porting Order id

application/json

Body

required

misc

object

type PortingOrderType (string)

Possible values: [full, partial]

A port can be either 'full' or 'partial'. When type is 'full' the other attributes should be omitted.

remaining_numbers_action string

Possible values: [keep, disconnect]

Remaining numbers can be either kept with their current service provider or disconnected. 'new_billing_telephone_number' is required when 'remaining_numbers_action' is 'keep'.

new_billing_phone_number string

New billing phone number for the remaining numbers. Used in case the current billing phone number is being ported to Telnyx. This will be set on your account with your current service provider and should be one of the numbers remaining on that account.

end_user

object

admin

object

entity_name string

Person Name or Company name requesting the port

auth_person_name string

Name of person authorizing the porting order

billing_phone_number string

Billing phone number associated with these phone numbers

account_number string

The authorized person's account number with the current service provider

tax_identifier string

European tax identification number. Applicable only in the European Union

pin_passcode string

PIN/passcode possibly required by the old service provider for extra verification

business_identifier string

European business identification number. Applicable only in the European Union

location

object

street_address string

First line of billing address

extended_address string

Second line of billing address

locality string

City or municipality of billing address

administrative_area string

State, province, or similar of billing address

postal_code string

Postal Code of billing address

country_code string

ISO3166-1 alpha-2 country code of billing address

documents

object

Can be specified directly or via the requirement_group_id parameter.

loa uuid

Returned ID of the submitted LOA via the Documents endpoint

invoice uuid

Returned ID of the submitted Invoice via the Documents endpoint

activation_settings

object

foc_datetime_requested date-time

ISO 8601 formatted Date/Time requested for the FOC date

phone_number_configuration

object

billing_group_id string

identifies the billing group to set on the numbers when ported

connection_id string

identifies the connection to set on the numbers when ported

messaging_profile_id string

identifies the messaging profile to set on the numbers when ported

emergency_address_id string

identifies the emergency address to set on the numbers when ported

tags string[]
requirement_group_id uuid

If present, we will read the current values from the specified Requirement Group into the Documents and Requirements for this Porting Order. Note that any future changes in the Requirement Group would have no impact on this Porting Order. We will return an error if a specified Requirement Group conflicts with documents or requirements in the same request.

requirements

object[]

List of requirements for porting numbers.

Array [

field_value stringrequired

identifies the document or provides the text value that satisfies this requirement

requirement_type_id stringrequired

Identifies the requirement type that the field_value fulfills

]

List of requirements for porting numbers.

user_feedback

object

user_rating integer

Once an order is ported, cancellation is requested or the request is cancelled, the user may rate their experience

user_comment string

A comment related to the customer rating.

webhook_url uri
customer_reference string

messaging

object

enable_messaging boolean

Indicates whether Telnyx will port messaging capabilities from the losing carrier. If false, any messaging capabilities will stay with their current provider.

200: Successful response

application/json

• Schema
• Example (from schema)

Schema

data

object

id uuid

Uniquely identifies this porting order

customer_reference string

A customer-specified reference number for customer bookkeeping purposes

created_at date-time

ISO 8601 formatted date indicating when the resource was created.

updated_at date-time

ISO 8601 formatted date indicating when the resource was created.

status

object

Porting order status

details

object[]

A list of 0 or more details about this porting order's status

Array [

code string

Possible values: [ACCOUNT_NUMBER_MISMATCH, AUTH_PERSON_MISMATCH, BTN_ATN_MISMATCH, ENTITY_NAME_MISMATCH, FOC_EXPIRED, FOC_REJECTED, LOCATION_MISMATCH, LSR_PENDING, MAIN_BTN_PORTING, OSP_IRRESPONSIVE, OTHER, PASSCODE_PIN_INVALID, PHONE_NUMBER_HAS_SPECIAL_FEATURE, PHONE_NUMBER_MISMATCH, PHONE_NUMBER_NOT_PORTABLE, PORT_TYPE_INCORRECT, PORTING_ORDER_SPLIT_REQUIRED, POSTAL_CODE_MISMATCH, RATE_CENTER_NOT_PORTABLE, SV_CONFLICT, SV_UNKNOWN_FAILURE]

Identifier of an exception type

description string

Description of an exception type

]

A list of 0 or more details about this porting order's status

value string

Possible values: [draft, in-process, submitted, exception, foc-date-confirmed, ported, cancelled, cancel-pending]

The current status of the porting order

Porting order status

support_key string

A key to reference this porting order when contacting Telnyx customer support. This information is not available in draft porting orders.

parent_support_key string

A key to reference for the porting order group when contacting Telnyx customer support. This information is not available for porting orders in draft state

porting_phone_numbers_count integer

Count of phone numbers associated with this porting order

old_service_provider_ocn string

Identifies the old service provider

documents

object

Can be specified directly or via the requirement_group_id parameter.

loa uuid

Returned ID of the submitted LOA via the Documents endpoint

invoice uuid

Returned ID of the submitted Invoice via the Documents endpoint

misc

object

type PortingOrderType (string)

Possible values: [full, partial]

A port can be either 'full' or 'partial'. When type is 'full' the other attributes should be omitted.

remaining_numbers_action string

Possible values: [keep, disconnect]

Remaining numbers can be either kept with their current service provider or disconnected. 'new_billing_telephone_number' is required when 'remaining_numbers_action' is 'keep'.

new_billing_phone_number string

New billing phone number for the remaining numbers. Used in case the current billing phone number is being ported to Telnyx. This will be set on your account with your current service provider and should be one of the numbers remaining on that account.

end_user

object

admin

object

entity_name string

Person Name or Company name requesting the port

auth_person_name string

Name of person authorizing the porting order

billing_phone_number string

Billing phone number associated with these phone numbers

account_number string

The authorized person's account number with the current service provider

tax_identifier string

European tax identification number. Applicable only in the European Union

pin_passcode string

PIN/passcode possibly required by the old service provider for extra verification

business_identifier string

European business identification number. Applicable only in the European Union

location

object

street_address string

First line of billing address

extended_address string

Second line of billing address

locality string

City or municipality of billing address

administrative_area string

State, province, or similar of billing address

postal_code string

Postal Code of billing address

country_code string

ISO3166-1 alpha-2 country code of billing address

activation_settings

object

foc_datetime_requested date-time

ISO 8601 formatted Date/Time requested for the FOC date

foc_datetime_actual date-time

ISO 8601 formatted Date/Time of the FOC date

fast_port_eligible boolean

Indicates whether this porting order is eligible for FastPort

activation_status PortingOrderActivationStatus (string)

Possible values: [New, Pending, Conflict, Cancel Pending, Failed, Concurred, Activate RDY, Disconnect Pending, Concurrence Sent, Old, Sending, Active, Cancelled]

Activation status

phone_number_configuration

object

billing_group_id string

identifies the billing group to set on the numbers when ported

connection_id string

identifies the connection to set on the numbers when ported

messaging_profile_id string

identifies the messaging profile to set on the numbers when ported

emergency_address_id string

identifies the emergency address to set on the numbers when ported

tags string[]

phone_number_type string

Possible values: [landline, local, mobile, national, shared_cost, toll_free]

The type of the phone number

description string

A description of the porting order

requirements

object[]

List of documentation requirements for porting numbers. Can be set directly or via the requirement_group_id parameter.

Array [

field_type string

Possible values: [document]

Type of value expected on field_value field

field_value string

identifies the document that satisfies this requirement

requirement_type_id string

Identifies the requirement type that meets this requirement

record_type string

Identifies the type of the resource.

]

requirements_met boolean

Is true when the required documentation is met

user_feedback

object

user_rating integer

Once an order is ported, cancellation is requested or the request is cancelled, the user may rate their experience

user_comment string

A comment related to the customer rating.

user_id uuid

Identifies the user (or organization) who requested the porting order

webhook_url uri

record_type string

Identifies the type of the resource.

messaging

object

Information about messaging porting process.

messaging_capable boolean

Indicates whether the porting order can also port messaging capabilities.

enable_messaging boolean

Indicates whether Telnyx will port messaging capabilities from the losing carrier. If false, any messaging capabilities will stay with their current provider.

messaging_port_status string

Possible values: [not_applicable, pending, activating, exception, canceled, partial_port_complete, ported]

The current status of the messaging porting.

messaging_port_completed boolean

Indicates whether the messaging porting has been completed.

Information about messaging porting process.

meta

object

phone_numbers_url string

Link to list all phone numbers

{
  "data": {
    "activation_settings": {
      "activation_status": null,
      "fast_port_eligible": true,
      "foc_datetime_actual": null,
      "foc_datetime_requested": "2022-04-08T15:00:00Z"
    },
    "created_at": "2022-03-24T14:22:28Z",
    "customer_reference": "Test1234",
    "description": "FP Telnyx",
    "documents": {
      "loa": null,
      "invoice": null
    },
    "end_user": {
      "admin": {
        "account_number": "123abc",
        "auth_person_name": "Porter McPortersen II",
        "billing_phone_number": "+13035551234",
        "business_identifier": "abc123",
        "entity_name": "Porter McPortersen",
        "pin_passcode": "1234",
        "tax_identifier": "1234abcd"
      },
      "location": {
        "administrative_area": "IL",
        "country_code": "US",
        "extended_address": "Suite 504",
        "locality": "Chicago",
        "postal_code": "60654",
        "street_address": "311 W. Superior St"
      }
    },
    "id": "eef10fb8-f3df-4c67-97c5-e18179723222",
    "misc": {
      "new_billing_phone_number": null,
      "remaining_numbers_action": null,
      "type": "full"
    },
    "old_service_provider_ocn": "Unreal Communications",
    "parent_support_key": null,
    "phone_number_configuration": {
      "billing_group_id": null,
      "connection_id": "1752379429071357070",
      "emergency_address_id": null,
      "messaging_profile_id": null,
      "tags": []
    },
    "phone_number_type": "local",
    "porting_phone_numbers_count": 1,
    "record_type": "porting_order",
    "requirements": [],
    "requirements_met": false,
    "status": {
      "details": [],
      "value": "draft"
    },
    "support_key": null,
    "updated_at": "2022-03-24T14:26:53Z",
    "user_feedback": {
      "user_comment": null,
      "user_rating": null
    },
    "messaging": {
      "messaging_capable": true,
      "enable_messaging": true,
      "messaging_port_status": "pending",
      "messaging_port_completed": false
    },
    "user_id": "40d68ba2-0847-4df2-be9c-b0e0cb673e75",
    "webhook_url": "https://example.com/porting_webhooks"
  },
  "meta": {
    "phone_numbers_url": "/v2/porting_phone_numbers?filter[porting_order_id]=eef10fb8-f3df-4c67-97c5-e18179723222"
  }
}

401: Unauthorized

422: Unprocessable entity. Check message field in response for details.

Request samples

• cURL

---

curl -L -X PATCH 'https://api.telnyx.com/v2/porting_orders/:id' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>' \
-d '{
  "misc": {
    "type": "full",
    "remaining_numbers_action": "disconnect",
    "new_billing_phone_number": "string"
  },
  "end_user": {
    "admin": {
      "entity_name": "Porter McPortersen",
      "auth_person_name": "Porter McPortersen II",
      "billing_phone_number": 13035551234,
      "account_number": "123abc",
      "tax_identifier": "1234abcd",
      "pin_passcode": 1234,
      "business_identifier": "abc123"
    },
    "location": {
      "street_address": "311 W. Superior St",
      "extended_address": "Suite 504",
      "locality": "Chicago",
      "administrative_area": "IL",
      "postal_code": "60654",
      "country_code": "US"
    }
  },
  "documents": {
    "loa": "64ffb720-04c7-455b-92d6-20fcca92e935",
    "invoice": "ce74b771-d23d-4960-81ec-8741b3862146"
  },
  "activation_settings": {
    "foc_datetime_requested": "2021-03-19T10:07:15.527Z"
  },
  "phone_number_configuration": {
    "billing_group_id": "f1486bae-f067-460c-ad43-73a92848f902",
    "connection_id": "f1486bae-f067-460c-ad43-73a92848f902",
    "messaging_profile_id": "f1486bae-f067-460c-ad43-73a92848f901",
    "emergency_address_id": "f1486bae-f067-460c-ad43-73a92848f902",
    "tags": [
      "abc",
      "123"
    ]
  },
  "requirement_group_id": "DE748D99-06FA-4D90-9F9A-F4B62696BADA",
  "requirements": [
    {
      "field_value": "9787fb5f-cbe5-4de4-b765-3303774ee9fe",
      "requirement_type_id": "59b0762a-b274-4f76-ac32-4d5cf0272e66"
    }
  ],
  "user_feedback": {
    "user_rating": 5,
    "user_comment": "I loved my experience porting numbers with Telnyx"
  },
  "webhook_url": "string",
  "customer_reference": "string",
  "messaging": {
    "enable_messaging": true
  }
}'

Response samples

• 200

---

{
  "data": {
    "activation_settings": {
      "activation_status": null,
      "fast_port_eligible": true,
      "foc_datetime_actual": null,
      "foc_datetime_requested": "2022-04-08T15:00:00Z"
    },
    "created_at": "2022-03-24T14:22:28Z",
    "customer_reference": "Test1234",
    "description": "FP Telnyx",
    "documents": {
      "loa": null,
      "invoice": null
    },
    "end_user": {
      "admin": {
        "account_number": "123abc",
        "auth_person_name": "Porter McPortersen II",
        "billing_phone_number": "+13035551234",
        "business_identifier": "abc123",
        "entity_name": "Porter McPortersen",
        "pin_passcode": "1234",
        "tax_identifier": "1234abcd"
      },
      "location": {
        "administrative_area": "IL",
        "country_code": "US",
        "extended_address": "Suite 504",
        "locality": "Chicago",
        "postal_code": "60654",
        "street_address": "311 W. Superior St"
      }
    },
    "id": "eef10fb8-f3df-4c67-97c5-e18179723222",
    "misc": {
      "new_billing_phone_number": null,
      "remaining_numbers_action": null,
      "type": "full"
    },
    "old_service_provider_ocn": "Unreal Communications",
    "parent_support_key": null,
    "phone_number_configuration": {
      "billing_group_id": null,
      "connection_id": "1752379429071357070",
      "emergency_address_id": null,
      "messaging_profile_id": null,
      "tags": []
    },
    "phone_number_type": "local",
    "porting_phone_numbers_count": 1,
    "record_type": "porting_order",
    "requirements": [],
    "requirements_met": false,
    "status": {
      "details": [],
      "value": "draft"
    },
    "support_key": null,
    "updated_at": "2022-03-24T14:26:53Z",
    "user_feedback": {
      "user_comment": null,
      "user_rating": null
    },
    "messaging": {
      "messaging_capable": true,
      "enable_messaging": true,
      "messaging_port_status": "pending",
      "messaging_port_completed": false
    },
    "user_id": "40d68ba2-0847-4df2-be9c-b0e0cb673e75",
    "webhook_url": "https://example.com/porting_webhooks"
  },
  "meta": {
    "phone_numbers_url": "/v2/porting_phone_numbers?filter[porting_order_id]=eef10fb8-f3df-4c67-97c5-e18179723222"
  }
}