Supplemental Port Order Requirements

Depending on the country and number type that you are trying to port in, there may be additional information that you will need to provide in order for the port to successfully process.

This supplemental information needed can be seen in the requirements array of the port order:

{
   "requirements": [
            {
                "field_type": "document",
                "field_value": null,
                "record_type": "porting_requirement",
                "requirement_status": "requirement-info-pending",
                "requirement_type_id": "a428786a-5dc2-41c0-b0fe-c32df4c1b5e2"
            },
            {
                "field_type": "document",
                "field_value": null,
                "record_type": "porting_requirement",
                "requirement_status": "requirement-info-pending",
                "requirement_type_id": "53970723-fbff-4f46-a975-f62be6c1a585"
            }
        ],
}

The requirements array is dynamic. The requirements for a US toll-free port order will be different than the requirements for an Australia mobile port order. When the order is created, the requirements array will be populated accordingly based on what you are trying to port in.

Each requirement has a unique ID associated with it. To obtain more context about what additional information is requested, you can either query for that particular requirement:

Request:

curl --location --request GET
'https://api.telnyx.com/v2/requirement_types/{{requirement_type_id}}' \
--header 'Authorization: Bearer [Redacted]' \

Response:

{
    "data": {
        "acceptance_criteria": {
            "locality_limit": null,
            "time_limit": "90 days"
        },
        "created_at": "2021-05-03T13:23:37Z",
        "description": "A copy of the latest phone bill from the current provider",
        "example": "Most recent phone bill",
        "id": "53970723-fbff-4f46-a975-f62be6c1a585",
        "name": "Latest Invoice",
        "record_type": "requirement_type",
        "type": "document",
        "updated_at": "2021-05-26T10:20:15Z"
    }
}

Or you can use the following endpoint to view more detailed information for all the requirements associated with your port order:

Request:

curl --location --request GET 'https://api.telnyx.com/v2/porting_orders/{{port_order_id}}/requirements' \
--header 'Authorization: Bearer [REDACTED]'

Response:

{
    "data": [
        {
            "field_type": "document",
            "field_value": "dd4ccd13-7d12-43a7-9e43-8c49998ed7e0",
            "record_type": "porting_requirement",
            "requirement_status": "approved",
            "requirement_type": {
                "acceptance_criteria": {
                    "acceptable_values": []
                },
                "description": "A copy of the latest phone bill from the current provider",
                "example": "Most recent phone bill",
                "id": "53970723-fbff-4f46-a975-f62be6c1a585",
                "name": "Latest Invoice",
                "type": "document"
            }
        },
        {
            "field_type": "document",
            "field_value": "dd4ccd13-7d12-43a7-9e43-8c49998ed7e0",
            "record_type": "porting_requirement",
            "requirement_status": "approved",
            "requirement_type": {
                "acceptance_criteria": {
                    "acceptable_values": []
                },
                "description": "A letter that authorizes Telnyx to port in the phone numbers on users ",
                "example": "A signed letter containing all phone numbers that you want to port into Telnyx",
                "id": "a428786a-5dc2-41c0-b0fe-c32df4c1b5e2",
                "name": "Letter of Authorization",
                "type": "document"
            }
        }
    ],
    "meta": {
        "page_number": 1,
        "page_size": 25,
        "total_pages": 1,
        "total_results": 2
    }
}

There are two types of requirements:

1. Document
2. Textual

The type of requirement can be determined by examining the field_type attribute of the requirement. Based on the field_type, you will need to provide different information to fulfill it.

If you are fulfilling a document requirement, issue the following PATCH request specifying the document ID as the field_value. Please ensure that you are associating the appropriate document with the appropriate requirement. Additionally, if you need more information on how to upload a document and obtain a document ID, you can refer to the Documents API.

curl --location --request PATCH 'https://api.telnyx.com/v2/porting_orders/{{port_order_id}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer [REDACTED]' \
--data-raw '{
    "requirements": [
      {   
          "requirement_type_id": "53970723-fbff-4f46-a975-f62be6c1a585",
          "field_value": "{{document_id_1}}"
      },
      {   
          "requirement_type_id": "88bba197-6d2a-4f7a-ac6a-54976585b79e",
          "field_value": "{{document_id_2}}"
       }
    ],
}'

If you are fulfilling a textual requirement, enter the relevant string of text as the field_value of the requirement and perform the following PATCH request:

curl --location --request PATCH 'https://api.telnyx.com/v2/porting_orders/{{port_order_id}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer [REDACTED]' \
--data-raw '{
    "requirements": [
      {   
          "field_value": “{{string_of_relevant_text}}",
          "requirement_type_id": "d9c099e2-ff2b-476d-99f2-775b4db121b0"
      }
    ],
}'

Each requirement on a port order also has a status associated with it to provide you with additional granularity on how your port order is being processed. A list of potential requirement statuses is shown below:

Value for “requirement_status”	Description
”requirement-info-pending”	Awaiting for user to submit information to fulfill the requirement
“requirement-info-under-review”	Information has been submitted and associated with the requirement. Now awaiting review from Telnyx Porting Ops
“requirement-info-exception”	The submitted information doesn’t match the acceptance criteria of the requirement. The user needs to resubmit new information to satisfy the requirement
“approved”	Requirement has been reviewed and validated by Telnyx Porting Ops

If you just want a high-level view of whether all requirements have been fulfilled and reviewed by the Telnyx Porting Ops team, you can check the requirements_status attribute on the port order.

• If the order contains ”requirements_status”: true, then all requirements on the port order have been fulfilled and approved
• if the order contains ”requirements_status”: false, then one or more requirements on the port order either haven’t been fulfilled, or haven’t been approved yet.