Fulfilling 'action' Requirements on Number Orders

After placing a number order, there may be some additional requirements for the user to fulfill before the order can be completed. The order will remain in a pending status until those additional requirements are fulfilled.

The user can make the following request to retrieve their number order:

Note

Don't forget to update YOUR_API_KEY here.

Request:

GET https://api.telnyx.com/v2/sub_number_orders/{id}
Authorization: Bearer YOUR_API_KEY


Response:

{
    "data": {
        "status": "pending",
        "phone_number_type": "local",
        "phone_numbers_count": 1,
        "order_request_id": "9ae7c893-49fe-488b-b7ff-6479c822c0e8",
        "created_at": "2023-12-08T21:40:09.046614+00:00",
        "updated_at": "2023-12-08T21:40:09.046615+00:00",
        "is_block_sub_number_order": false,
        "regulatory_requirements": [
            {
                "requirement_id": "2e0c523c-004a-40f0-a88c-a0961acd9c20",
                "record_type": "phone_number_regulatory_requirement",
                "field_type": "textual"
            },
            {
                "requirement_id": "0ba49bfa-8a0b-4e38-95ba-f1291507fad4",
                "record_type": "phone_number_regulatory_requirement",
                "field_type": "document"
            }
        ],
        "country_code": "GB",
        "user_id": "40d68ba2-0847-4df2-be9c-b0e0cb673e75",
        "requirements_met": false,
        "customer_reference": null,
        "id": "d5a6b3ec-9c83-4a49-a2c6-1174988d4635",
        "record_type": "sub_number_order"
    }
}

The additional requirements are listed in the regulatory_requirements array. Each requirement has its own unique requirement_id. You can make a request to view more information about each of these requirements, as shown below:

Request:

GET https://api.telnyx.com/v2/requirement_types?filter[id][in][]={requirement_id_1}&filter[id][in][]={requirement_id_2}&...

Response:

{
    "data": [
        {
            "id": "2e0c523c-004a-40f0-a88c-a0961acd9c20",
            "name": "TAX ID / VAT / Passport or ID number ",
            "type": "textual",
            "description": "If the number you wish to port belongs to a company, please enter the TAX ID or VAT.\nIf the number you wish to port does not belong to a company, please provide your Passport or ID number ",
            "record_type": "requirement_type",
            "updated_at": "2021-10-22T14:11:38Z",
            "created_at": "2021-10-22T14:11:38Z",
            "acceptance_criteria": {
                "max_length": null,
                "time_limit": null,
                "locality_limit": null,
                "acceptable_values": [],
                "min_length": null,
                "acceptable_characters": null
            },
            "example": "12345678910"
        },
        {
            "id": "0ba49bfa-8a0b-4e38-95ba-f1291507fad4",
            "name": "Proof of address (National)",
            "type": "document",
            "description": "A recent invoice or utility bill showing proof of address within the country",
            "record_type": "requirement_type",
            "updated_at": "2021-07-08T14:35:45Z",
            "created_at": "2021-06-24T13:57:43Z",
            "acceptance_criteria": {
                "max_length": null,
                "time_limit": "Within the last 6 months",
                "locality_limit": null,
                "acceptable_values": [],
                "min_length": null,
                "acceptable_characters": null
            },
            "example": "Utility bill or invoice"
        }
    ],
    "meta": {
        "page_number": 1,
        "page_size": 20,
        "total_pages": 1,
        "total_results": 2
    }
}

---

We have recently introduced a new requirement type, called action. These requirements cannot be fulfilled by providing information and/or submitting documents. An action requires the user to take some external action to meet the requirement. These actions are unique depending on what phone number you are ordering.

The remainder of this guide will cover the different possible actions you may encounter, and how to satisfy these requirements.

For AU mobile number orders, the end user is required to undergo ID verification. To facilitate the ID verification process, we've partnered with Onfido for a secure and efficient experience.

To satisfy this requirement, you must:

1. Generate a unique link and share it with the end user for accessing Onfido's secure ID verification portal.
2. The end user must visit the link and submit an ID verification request.
3. Once submitted, our team will review the verification. If successful, the ID verification requirement will be marked as completed on your order.

To generate the Onfido ID verification link, please perform a POST 'https://api.telnyx.com/v2/external_requirements/b7c72fb8-fa08-4529-aaf6-b9117d3f3698/sub_number_orders/{sub_order_id}' request, where {sub_order_id} is the id for your AU mobile sub number order. The body of the API request must include the end user’s first name and last name. An example API request is shown below:

Request:

curl --location --request POST 'https://api.telnyx.com/v2/external_requirements/b7c72fb8-fa08-4529-aaf6-b9117d3f3698/sub_number_orders/{sub_order_id}' \
--header 'Authorization: Bearer [redacted]' \
--header 'Content-Type: application/json' \
--data-raw '{
    "requirement": {
        "first_name": "Value 1",
        "last_name": "Value 2"
    }
}'

Response:

{
    "data": {
        "sub_order_id": "{{sub_order_id}}",
        "regulatory_requirement_id": "b7c72fb8-fa08-4529-aaf6-b9117d3f3698",
        "requirement_action": {
            "type": "url",
            "value": "https://us.onfido.app/l/{id}"
        }
    }
}

A URL is returned in the value attribute of the API response. When the end user visits this URL, they will be automatically redirected to the Onfido ID verification portal. Once the ID verification request is submitted and approved, this requirement on the number order will be marked as completed.