Requirement Groups

Requirement Groups allow you to view, manage, and fulfill regulatory requirements in advance for a particular order type. By creating a Requirement Group, you can pre-fill all necessary information and documentation just once, and then reuse this group across multiple orders. This eliminates the need to re-upload the same requirements for each order, saving you time and ensuring accuracy.

1. Create a Requirement Group: Create a new Requirement Group for the specific order (country, phone number type, port/purchase) you need.
2. Fulfill and validate: Fill out all necessary regulatory information and upload any required documents, ensuring all information is accurate and complete.
3. Associate with orders: Associate the Requirement Group ID with your order. The pre-filled requirements will automatically be applied to the order.
4. Regulatory review and approval: The order will undergo the standard regulatory requirement review process. The values provided may be approved or rejected.

The remainder of this guide will walk you through how to integrate with the Requirement Groups API.

Requirement groups are an optional feature in most countries. You can use them if you prefer this flow. Or you can manage your orders without requirement groups.

However in the following countries, it is mandatory to use fulfilled requirement groups when placing a number order:

• CH (Switzerland)
• DK (Denmark)
• IT (Italy)
• NO (Norway)
• PT (Portugal)
• SE (Sweden)

Where fulfilled means that every requirement in the group has an associated value. You could not create an order with an empty requirement group.

To create a requirement group, perform a POST v2/requirement_groups API request (API reference here). There are 3 required attributes in the body of the request:

• country_code: The country that you would like to order/port in. Only ISO Alpha-2 country codes are acceptable values.
• phone_number_type: The phone number type that you would like to order/port in. Acceptable values include local, toll_free, national, mobile, and shared_cost.
• action: The type of order you are creating a requirement group for. Acceptable values are ordering or porting.

You can also add a customer_reference in the body of the request to label each requirement group. customer_reference is optional.

Requirement groups can only be associated with orders that match its country_code + phone_number_type + action combination. For example, if you created a DE local ordering requirement group, it can only be applied to DE local number orders. It could not be applied to anything else (like PT toll_free ports).

An example request is shown below, for a DE local, ordering requirement group:

curl --location --request POST 'https://api.telnyx.com/v2/requirement_groups' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data '{
  "country_code": "DE",
  "phone_number_type": "local",
  "action": "ordering"
}'

Response:

{
    "data": {
        "country_code": "DE",
        "action": "ordering",
        "created_at": "2024-07-15T19:00:59.571887Z",
        "id": "4689d4ed-ad34-4a52-9909-8f3b244dc9c8",
        "updated_at": "2024-07-15T19:00:59.571891Z",
        "phone_number_type": "local",
        "customer_reference": null,
        "record_type": "requirement_group",
        "regulatory_requirements": [
            {
                "field_value": "",
                "created_at": "2024-07-15T19:00:59.594804Z",
                "updated_at": "2024-07-15T19:00:59.594810Z",
                "requirement_id": "2708e569-696a-4fc7-9305-5fdb3eb9c7dd",
                "field_type": "textual"
            },
            {
                "field_value": "",
                "created_at": "2024-07-15T19:00:59.607812Z",
                "updated_at": "2024-07-15T19:00:59.607818Z",
                "requirement_id": "6d3e2643-efaa-4bd3-8c31-77b6cda1d6a2",
                "field_type": "document"
            },
            {
                "field_value": "",
                "created_at": "2024-07-15T19:00:59.617298Z",
                "updated_at": "2024-07-15T19:00:59.617303Z",
                "requirement_id": "95cac7a7-cf24-4d34-81e4-e2d01a35adda",
                "field_type": "document"
            },
            {
                "field_value": "",
                "created_at": "2024-07-15T19:00:59.626566Z",
                "updated_at": "2024-07-15T19:00:59.626570Z",
                "requirement_id": "a3a856c0-2811-4eee-9607-ea60df9f5c32",
                "field_type": "document"
            },
            {
                "field_value": "",
                "created_at": "2024-07-15T19:00:59.635833Z",
                "updated_at": "2024-07-15T19:00:59.635837Z",
                "requirement_id": "a7d9a3a3-70ed-4cb4-821b-b94e8ea6dc9b",
                "field_type": "address"
            }
        ]
    }
}

You can list all requirement groups by performing a GET v2/requirement_groups API request (API reference here). An example request is shown below:

curl --location --request GET 'https://api.telnyx.com/v2/requirement_groups' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY'

Response:

{
   "data":[
      {
         "country_code":"DE",
         "action":"ordering",
         "created_at":"2024-07-15T19:00:59.571887Z",
         "id":"4689d4ed-ad34-4a52-9909-8f3b244dc9c8",
         "updated_at":"2024-07-15T19:00:59.571891Z",
         "phone_number_type":"local",
         "customer_reference":null,
         "record_type":"requirement_group",
         "regulatory_requirements":[
            {
               "field_value":"",
               "created_at":"2024-07-15T19:00:59.594804Z",
               "updated_at":"2024-07-15T19:00:59.594810Z",
               "requirement_id":"2708e569-696a-4fc7-9305-5fdb3eb9c7dd",
               "field_type":"textual"
            },
            {
               "field_value":"",
               "created_at":"2024-07-15T19:00:59.607812Z",
               "updated_at":"2024-07-15T19:00:59.607818Z",
               "requirement_id":"6d3e2643-efaa-4bd3-8c31-77b6cda1d6a2",
               "field_type":"document"
            },
            {
               "field_value":"",
               "created_at":"2024-07-15T19:00:59.617298Z",
               "updated_at":"2024-07-15T19:00:59.617303Z",
               "requirement_id":"95cac7a7-cf24-4d34-81e4-e2d01a35adda",
               "field_type":"document"
            },
            {
               "field_value":"",
               "created_at":"2024-07-15T19:00:59.626566Z",
               "updated_at":"2024-07-15T19:00:59.626570Z",
               "requirement_id":"a3a856c0-2811-4eee-9607-ea60df9f5c32",
               "field_type":"document"
            },
            {
               "field_value":"",
               "created_at":"2024-07-15T19:00:59.635833Z",
               "updated_at":"2024-07-15T19:00:59.635837Z",
               "requirement_id":"a7d9a3a3-70ed-4cb4-821b-b94e8ea6dc9b",
               "field_type":"address"
            }
         ]
      }
   ],
   "meta":{
      "total_pages":1,
      "total_results":1,
      "page_number":1,
      "page_size":25
   }
}

You can also query for a specific requirement group by including the id in the URL path (API reference here). An example request is shown below:

curl --location --request GET 'https://api.telnyx.com/v2/requirement_groups/4689d4ed-ad34-4a52-9909-8f3b244dc9c8' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY'

Response:

{
    "data": {
        "country_code": "DE",
        "action": "ordering",
        "created_at": "2024-07-15T19:00:59.571887Z",
        "id": "4689d4ed-ad34-4a52-9909-8f3b244dc9c8",
        "updated_at": "2024-07-15T19:00:59.571891Z",
        "phone_number_type": "local",
        "customer_reference": null,
        "record_type": "requirement_group",
        "regulatory_requirements": [
            {
                "field_value": "",
                "created_at": "2024-07-15T19:00:59.594804Z",
                "updated_at": "2024-07-15T19:00:59.594810Z",
                "requirement_id": "2708e569-696a-4fc7-9305-5fdb3eb9c7dd",
                "field_type": "textual"
            },
            {
                "field_value": "",
                "created_at": "2024-07-15T19:00:59.607812Z",
                "updated_at": "2024-07-15T19:00:59.607818Z",
                "requirement_id": "6d3e2643-efaa-4bd3-8c31-77b6cda1d6a2",
                "field_type": "document"
            },
            {
                "field_value": "",
                "created_at": "2024-07-15T19:00:59.617298Z",
                "updated_at": "2024-07-15T19:00:59.617303Z",
                "requirement_id": "95cac7a7-cf24-4d34-81e4-e2d01a35adda",
                "field_type": "document"
            },
            {
                "field_value": "",
                "created_at": "2024-07-15T19:00:59.626566Z",
                "updated_at": "2024-07-15T19:00:59.626570Z",
                "requirement_id": "a3a856c0-2811-4eee-9607-ea60df9f5c32",
                "field_type": "document"
            },
            {
                "field_value": "",
                "created_at": "2024-07-15T19:00:59.635833Z",
                "updated_at": "2024-07-15T19:00:59.635837Z",
                "requirement_id": "a7d9a3a3-70ed-4cb4-821b-b94e8ea6dc9b",
                "field_type": "address"
            }
        ]
    }
}

The regulatory_requirements array lists each of the requirements that need to be fulfilled for your order (country + phone_number_type + action). Each individual requirement has a unique requirement_id.

Using the GET /v2/requirement_types/:id API request (API reference here) you can view additional information for each requirement and how to fulfill them. An example request is below:

curl --location --request GET 'https://api.telnyx.com/v2/requirement_types/2708e569-696a-4fc7-9305-5fdb3eb9c7dd' \
--header 'Authorization: Bearer YOUR_API_KEY'

Response:

{
    "data": {
        "id": "2708e569-696a-4fc7-9305-5fdb3eb9c7dd",
        "name": "Contact Info",
        "type": "textual",
        "description": "Name, business name, and contact phone numbers",
        "record_type": "requirement_type",
        "updated_at": "2024-01-30T20:17:30Z",
        "created_at": "2021-04-30T15:48:58Z",
        "acceptance_criteria": {
            "max_length": null,
            "acceptable_characters": null,
            "acceptable_values": [],
            "min_length": null,
            "time_limit": null,
            "locality_limit": null
        },
        "example": "Name, business name, and contact phone numbers"
    }
}

Please keep in mind the requirement's acceptance criteria. If the value you provide does not meet the requirement's acceptance criteria, it will be rejected.

There are four possible field_type values:

• textual
• address
• document
• action

Each type has different rules for fulfilling the requirement.

To fulfill a textual requirement, enter a string of characters. The value entered must comply with the requirement's acceptance_criteria.

To fulfill an address requirement, an address id must be provided as the field value. Create an address using the POST v2/addresses endpoint (API reference here). Upon successful creation, the address will have a unique id associated with it (for example 1293384261075731499). Pass that id as the field_value for the address ordering requirement. You cannot write out the address as a string (i.e. "600 Congress Avenue, Austin, TX, 78701"). You must create the address, and pass the address id as the field_value.

To fulfill a document requirement, a document id must be provided as the field value. Upload the document using the Documents API. Upon successful upload, an id will be returned in the response that corresponds to the document (for example 6a09cdc3-8948-47f0-aa62-74ac943d6c58). Pass that id as the field_value for the document ordering requirement. There are a few ways that you can upload a document. You can upload a document by multipart:

curl --location --request POST 'https://api.telnyx.com/v2/documents' \
--header 'Content-Type: multipart/form-data' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--form 'file=@/Users/xd/Downloads/threads-bugs.pdf'

Or upload as a base64 encoded file:

curl --location --request POST 'https://api.telnyx.com/v2/documents' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data-raw '{
"file": "{Base64 Encoded File}"
}'

You can check your documents in the Telnyx Portal by following these steps: Click on the dropdown arrow next to your profile icon in the upper right corner. Select "Documents." Click "Preview" on the document you want to view.

An action requirement is unique, and very rare. Please see our separate developer guide to learn more about how to handle action requirement types. These cannot be fulfilled in a requirement group.

After performing the POST v2/requirement_groups request to create a group, you can perform a PATCH v2/requirement_groups/:id request to update the requirements (API reference here). In the body of the request, specify the requirement_id and the associated value(s). An example request is shown below:

curl --location --request PATCH 'https://api.telnyx.com/v2/requirement_groups/4689d4ed-ad34-4a52-9909-8f3b244dc9c8' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data '{
    "regulatory_requirements": [
        {
            "requirement_id": "2708e569-696a-4fc7-9305-5fdb3eb9c7dd",
            "field_value": "test_123"
        }
    ]
}'

Response:

{
    "data": {
        "country_code": "DE",
        "action": "ordering",
        "created_at": "2024-07-15T19:00:59.571887Z",
        "id": "4689d4ed-ad34-4a52-9909-8f3b244dc9c8",
        "updated_at": "2024-07-15T19:00:59.571891Z",
        "phone_number_type": "local",
        "customer_reference": null,
        "record_type": "requirement_group",
        "regulatory_requirements": [
            {
                "field_value": "test_123",
                "created_at": "2024-07-15T19:00:59.594804Z",
                "updated_at": "2024-07-15T19:55:55.637524Z",
                "requirement_id": "2708e569-696a-4fc7-9305-5fdb3eb9c7dd",
                "field_type": "textual"
            },
            {
                "field_value": "",
                "created_at": "2024-07-15T19:00:59.607812Z",
                "updated_at": "2024-07-15T19:00:59.607818Z",
                "requirement_id": "6d3e2643-efaa-4bd3-8c31-77b6cda1d6a2",
                "field_type": "document"
            },
            {
                "field_value": "",
                "created_at": "2024-07-15T19:00:59.617298Z",
                "updated_at": "2024-07-15T19:00:59.617303Z",
                "requirement_id": "95cac7a7-cf24-4d34-81e4-e2d01a35adda",
                "field_type": "document"
            },
            {
                "field_value": "",
                "created_at": "2024-07-15T19:00:59.626566Z",
                "updated_at": "2024-07-15T19:00:59.626570Z",
                "requirement_id": "a3a856c0-2811-4eee-9607-ea60df9f5c32",
                "field_type": "document"
            },
            {
                "field_value": "",
                "created_at": "2024-07-15T19:00:59.635833Z",
                "updated_at": "2024-07-15T19:00:59.635837Z",
                "requirement_id": "a7d9a3a3-70ed-4cb4-821b-b94e8ea6dc9b",
                "field_type": "address"
            }
        ]
    }
}

If you already know the requirements, you can create the requirement group and provide all field values in a single request. Just include the regulatory_requirements array in the POST /v2/requirement_groups API request (API reference here). An example request is shown below:

curl --location --request POST 'https://api.telnyx.com/v2/requirement_groups' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data '{
    "country_code": "DE",
    "phone_number_type": "local",
    "action": "ordering",
    "regulatory_requirements": [
        {
            "field_value": "test_123",
            "requirement_id": "2708e569-696a-4fc7-9305-5fdb3eb9c7dd"
        },
        {
            "field_value": "99c3a812-a2cc-4eef-ae32-75dbcfc93d58",
            "requirement_id": "6d3e2643-efaa-4bd3-8c31-77b6cda1d6a2"
        },
        {
            "field_value": "99c3a812-a2cc-4eef-ae32-75dbcfc93d58",
            "requirement_id": "95cac7a7-cf24-4d34-81e4-e2d01a35adda"
        },
        {
            "field_value": "99c3a812-a2cc-4eef-ae32-75dbcfc93d58",
            "requirement_id": "a3a856c0-2811-4eee-9607-ea60df9f5c32"
        },
        {
            "field_value": "2473491569332717266",
            "requirement_id": "a7d9a3a3-70ed-4cb4-821b-b94e8ea6dc9b"
        }
    ]
}'

Response:

{
    "data": {
        "updated_at": "2024-07-15T21:50:15.052511Z",
        "customer_reference": null,
        "action": "ordering",
        "country_code": "DE",
        "phone_number_type": "local",
        "id": "27add064-a56c-4574-8725-9fecd4c52710",
        "created_at": "2024-07-15T21:50:15.052502Z",
        "record_type": "requirement_group",
        "regulatory_requirements": [
            {
                "updated_at": "2024-07-15T21:50:15.068740Z",
                "field_type": "textual",
                "field_value": "test_123",
                "requirement_id": "2708e569-696a-4fc7-9305-5fdb3eb9c7dd",
                "created_at": "2024-07-15T21:50:15.068736Z"
            },
            {
                "updated_at": "2024-07-15T21:50:15.077719Z",
                "field_type": "document",
                "field_value": "99c3a812-a2cc-4eef-ae32-75dbcfc93d58",
                "requirement_id": "6d3e2643-efaa-4bd3-8c31-77b6cda1d6a2",
                "created_at": "2024-07-15T21:50:15.077716Z"
            },
            {
                "updated_at": "2024-07-15T21:50:15.084576Z",
                "field_type": "document",
                "field_value": "99c3a812-a2cc-4eef-ae32-75dbcfc93d58",
                "requirement_id": "95cac7a7-cf24-4d34-81e4-e2d01a35adda",
                "created_at": "2024-07-15T21:50:15.084573Z"
            },
            {
                "updated_at": "2024-07-15T21:50:15.093612Z",
                "field_type": "document",
                "field_value": "99c3a812-a2cc-4eef-ae32-75dbcfc93d58",
                "requirement_id": "a3a856c0-2811-4eee-9607-ea60df9f5c32",
                "created_at": "2024-07-15T21:50:15.093607Z"
            },
            {
                "updated_at": "2024-07-15T21:50:15.103259Z",
                "field_type": "address",
                "field_value": "2473491569332717266",
                "requirement_id": "a7d9a3a3-70ed-4cb4-821b-b94e8ea6dc9b",
                "created_at": "2024-07-15T21:50:15.103255Z"
            }
        ]
    }
}

First, perform a search request and identify the phone number(s) you would like to purchase.

Then, place a number order using the POST v2/number_orders API request (API reference here). In the body of the request, include the appropriate requirement_group_id in each phone_number object. An example request is shown below:

curl --location --request POST 'https://api.telnyx.com/v2/number_orders' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data '{
    "phone_numbers": [
        {
            "phone_number": "{{e.164_phone_number}}",
            "requirement_group_id": "4689d4ed-ad34-4a52-9909-8f3b244dc9c8"
        }
    ]
}'

Response:

{
    "data": {
        "billing_group_id": null,
        "requirements_met": false,
        "phone_numbers": [
            {
                "requirements_met": false,
                "country_code": "DE",
                "regulatory_requirements": [],
                "status": "pending",
                "requirements_status": "requirement-info-pending",
                "id": "041c50b4-92b6-4ad7-956e-bc2d68418ad1",
                "phone_number": "{{e.164_phone_number}}",
                "phone_number_type": "local",
                "bundle_id": null,
                "record_type": "number_order_phone_number"
            }
        ],
        "sub_number_orders_ids": [
            "e001547a-6d1e-4fcc-8b77-22ba5d86feca"
        ],
        "status": "pending",
        "created_at": "2024-07-15T21:34:41.664687+00:00",
        "id": "5ef8ab9b-6ddb-475b-bfbe-50dfbca30daa",
        "updated_at": "2024-07-15T21:34:41.664689+00:00",
        "phone_numbers_count": 1,
        "customer_reference": null,
        "connection_id": null,
        "messaging_profile_id": null,
        "record_type": "number_order"
    }
}

If you retrieve the number order, you will see that the values in the requirement group have populated the order and are pending review.

note

Requirement Groups are optional for ordering in most countries. However, they are mandatory in the following countries:

• CH (Switzerland)
• DK (Denmark)
• IT (Italy)
• NO (Norway)
• PT (Portugal)
• SE (Sweden)

You can also update an existing pending number order using your requirement group.

When updating an existing pending order with a new requirement group:

• the requirement group must be fulfilled. If there are any unfulfilled (missing field_value) requirements, the API request will fail.
• the request will only update non-approved requirements on the order. If a requirement on the order is already in an approved status, the field value will remain unchanged.
• the number order does not automatically synchronize with the requirement group. In other words, lets say that you have a number order and update it with Requirement Group A. Some time passes, and you change one of the values in Requirement Group A. To update the pending number order, you must perform another API request. The pending number order will not synchronize automatically when you change Requirement Group A.

Perform a POST v2/sub_number_orders/{{sub_number_order_id}}/requirement_group request (API reference here) to update the entire pending Sub Number Order with a requirement group. {{sub_number_order_id}} in the URL path is the id of the Sub Number Order (API reference here). Include the applicable requirement_group_id in the body of the request. An example request is shown below:

curl --location --request POST 'https://api.telnyx.com/v2/sub_number_orders/bb6c79ed-1813-4f67-82d8-26229b277ca7/requirement_group' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data '{
    "requirement_group_id":"27add064-a56c-4574-8725-9fecd4c52710"
}'

Response:

{
    "data": {
        "order_request_id": "c4d46582-9628-4a17-8b5e-866c3cfd2d05",
        "id": "bb6c79ed-1813-4f67-82d8-26229b277ca7",
        "is_block_sub_number_order": false,
        "created_at": "2024-11-18T19:59:58.916287Z",
        "phone_number_type": "local",
        "status": "pending",
        "requirements_met": false,
        "phone_numbers_count": 1,
        "regulatory_requirements": [
            {
                "field_type": "textual",
                "requirement_id": "2708e569-696a-4fc7-9305-5fdb3eb9c7dd",
                "record_type": "phone_number_regulatory_requirement"
            },
            {
                "field_type": "document",
                "requirement_id": "6d3e2643-efaa-4bd3-8c31-77b6cda1d6a2",
                "record_type": "phone_number_regulatory_requirement"
            },
            {
                "field_type": "document",
                "requirement_id": "95cac7a7-cf24-4d34-81e4-e2d01a35adda",
                "record_type": "phone_number_regulatory_requirement"
            },
            {
                "field_type": "document",
                "requirement_id": "a3a856c0-2811-4eee-9607-ea60df9f5c32",
                "record_type": "phone_number_regulatory_requirement"
            },
            {
                "field_type": "address",
                "requirement_id": "a7d9a3a3-70ed-4cb4-821b-b94e8ea6dc9b",
                "record_type": "phone_number_regulatory_requirement"
            }
        ],
        "phone_numbers": [
            {
                "id": "da7b26fa-831a-4d30-b538-c64398731a20",
                "phone_number_type": "local",
                "requirements_met": false,
                "status": "pending",
                "regulatory_requirements": [
                    {
                        "field_type": "textual",
                        "field_value": "test_123",
                        "requirement_id": "2708e569-696a-4fc7-9305-5fdb3eb9c7dd",
                        "status": "pending-approval"
                    },
                    {
                        "field_type": "document",
                        "field_value": "99c3a812-a2cc-4eef-ae32-75dbcfc93d58",
                        "requirement_id": "6d3e2643-efaa-4bd3-8c31-77b6cda1d6a2",
                        "status": "pending-approval"
                    },
                    {
                        "field_type": "document",
                        "field_value": "99c3a812-a2cc-4eef-ae32-75dbcfc93d58",
                        "requirement_id": "95cac7a7-cf24-4d34-81e4-e2d01a35adda",
                        "status": "pending-approval"
                    },
                    {
                        "field_type": "document",
                        "field_value": "99c3a812-a2cc-4eef-ae32-75dbcfc93d58",
                        "requirement_id": "a3a856c0-2811-4eee-9607-ea60df9f5c32",
                        "status": "pending-approval"
                    },
                    {
                        "field_type": "address",
                        "field_value": "2473491569332717266",
                        "requirement_id": "a7d9a3a3-70ed-4cb4-821b-b94e8ea6dc9b",
                        "status": "pending-approval"
                    }
                ],
                "record_type": "number_order_phone_number",
                "bundle_id": null,
                "country_code": "DE",
                "requirements_status": "requirement-info-under-review",
                "phone_number": "{{e.164_phone_number}}"
            }
        ],
        "country_code": "DE",
        "customer_reference": null,
        "updated_at": "2024-11-18T19:59:58.916287Z",
        "record_type": "sub_number_order"
    }
}

Perform a PATCH v2/porting_orders/:id request (API reference here) and include the requirement_group_id in the body of the request. An example request is shown below:

curl --location --request PATCH 'https://api.telnyx.com/v2/porting_orders/e575b610-983a-4598-a4b7-a9e5ba5a6a90' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data '{"requirement_group_id": "a03c5ddc-b366-4db6-974e-d7568ebb1876"}'

This request can be performed when the order is in a draft, in-process, or exception status.

Any existing values for requirements will be overwritten by the requirement group.

Requirement group pre-approval lets you submit a requirement group for review before placing a number order. Once a requirement group is approved, any order it is associated with will become eligible for immediate activation, bypassing or minimizing the standard regulatory review process. This helps streamline ordering and speed up number activation.

1. Request pre-approval Submit a completed requirement group for pre-approval using the POST v2/requirement_groups/:id/submit_for_approval request (API reference here). Example request shown below:

curl --location --request POST 'https://api.telnyx.com/v2/requirement_groups/6097d47e-92f5-4548-a9d4-aa6f45ef8070/submit_for_approval' \
--header 'Authorization: Bearer YOUR_API_KEY'

Response:

{
    "data": {
        "phone_number_type": "local",
        "status": "pending-approval",
        "country_code": "DE",
        "action": "ordering",
        "updated_at": "2025-10-08T19:28:59.649588Z",
        "id": "6097d47e-92f5-4548-a9d4-aa6f45ef8070",
        "created_at": "2025-10-08T19:28:10.601709Z",
        "customer_reference": null,
        "user_id": "c6b8da5d-0b1a-48fc-965d-91f96a34c847",
        "record_type": "requirement_group",
        "regulatory_requirements": [
            {
                "status": "pending-approval",
                "field_value": "test_123",
                "field_type": "textual",
                "updated_at": "2025-10-08T19:28:59.656700Z",
                "expires_at": null,
                "created_at": "2025-10-08T19:28:10.706749Z",
                "requirement_id": "2708e569-696a-4fc7-9305-5fdb3eb9c7dd"
            },
            {
                "status": "pending-approval",
                "field_value": "99c3a812-a2cc-4eef-ae32-75dbcfc93d58",
                "field_type": "document",
                "updated_at": "2025-10-08T19:28:59.660113Z",
                "expires_at": null,
                "created_at": "2025-10-08T19:28:10.721600Z",
                "requirement_id": "6d3e2643-efaa-4bd3-8c31-77b6cda1d6a2"
            },
            {
                "status": "pending-approval",
                "field_value": "99c3a812-a2cc-4eef-ae32-75dbcfc93d58",
                "field_type": "document",
                "updated_at": "2025-10-08T19:28:59.663683Z",
                "expires_at": null,
                "created_at": "2025-10-08T19:28:10.735100Z",
                "requirement_id": "95cac7a7-cf24-4d34-81e4-e2d01a35adda"
            },
            {
                "status": "pending-approval",
                "field_value": "99c3a812-a2cc-4eef-ae32-75dbcfc93d58",
                "field_type": "document",
                "updated_at": "2025-10-08T19:28:59.666476Z",
                "expires_at": null,
                "created_at": "2025-10-08T19:28:10.751180Z",
                "requirement_id": "a3a856c0-2811-4eee-9607-ea60df9f5c32"
            },
            {
                "status": "pending-approval",
                "field_value": "2473491569332717266",
                "field_type": "address",
                "updated_at": "2025-10-08T19:28:59.669212Z",
                "expires_at": null,
                "created_at": "2025-10-08T19:28:10.763907Z",
                "requirement_id": "a7d9a3a3-70ed-4cb4-821b-b94e8ea6dc9b"
            }
        ]
    }
}

2. Pre-approval review
   Telnyx reviews the submitted requirement group. If all requirements are met, the group’s status is set to approved. Otherwise, it may move to declined or remain pending approval until the review is complete.

3. Place a number order
   When placing a number order, associate the requirement_group_id of an approved group. Orders using approved groups are eligible for immediate activation, provided all other checks—such as address validation—pass successfully.

• unapproved — Default status. The requirement group exists but hasn’t been submitted for pre-approval. It may be partially completed, but it hasn’t undergone review. Orders using unapproved groups follow the standard review process.
• pending approval — The group has been submitted and is under review.
• approved — The group has passed review and is eligible for automatic activation when referenced in a number order.
• declined — If one or more requirements are rejected during pre-approval, the group transitions to declined. You can still use declined groups when placing orders, but those orders will go through the standard KYC or regulatory review process.
• expired — Some regulatory requirements are valid only for a limited time (for example, 90 days). Once a required document or proof exceeds its validity window, the requirement group automatically transitions to expired. To see an individual requirement's expiration date (if any), you can review the regulatory_requirements.expires_at attribute for each requirement_id. You can still use expired groups when placing orders, but those orders will go through the standard KYC or regulatory review process.

• Country coverage — Requirement group pre-approval is supported in most countries, but not all. Some countries, such as Italy, don’t support pre-approval. Orders for numbers in these countries automatically follow the regular review process, even if an approved group is associated.
• Address validation — If the requirement group has an “address” requirement, make sure that the phone numbers ordered comply with that address requirement. For example, if your group had an “Address matching the DID area code” requirement and the approved address was for “Munich”, order a phone number in Munich. If you order a phone number in a different area (i.e. “Berlin” in this case), then the order will not be auto-approved and will undergo regular KYC review.
  • If the requirement specifies an address within the same area code, only numbers in that locality are eligible for automatic activation.
  • If the requirement specifies a national address, the address must be within the same country as the ordered phone number. If these conditions aren’t met, the order won’t activate automatically (even if it references an approved requirement group) and the address requirement will be declined.
• Fallback to standard flow — If an order references a requirement group that isn’t approved or is in another status, the system defaults to the standard order review process.

To delete a requirement group, perform a DELETE v2/requirement_groups/:id API request (API reference here). An example request is shown below:

curl --location --request DELETE 'https://api.telnyx.com/v2/requirement_groups/4689d4ed-ad34-4a52-9909-8f3b244dc9c8' \
--header 'Authorization: Bearer YOUR_API_KEY'

Response:

204 no content