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 it's 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:

Request:
curl --location --request POST 'https://api.telnyx.com/v2/requirement_groups' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: ••••••' \
--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:

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

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:

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

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 out 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:

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

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"
    }
}

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. "311 W Superior St, Chicago, IL, 60654"). 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 [REDACTED]' \
--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 [REDACTED]' \
--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:

Request:
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: ••••••' \
--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:

Request:
curl --location --request POST 'https://api.telnyx.com/v2/requirement_groups' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: ••••••' \
--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:

Request:
curl --location --request POST 'https://api.telnyx.com/v2/number_orders' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--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)

Coming soon!

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:

Request:
curl --location --request PATCH 'https://api.telnyx.com/v2/porting_orders/e575b610-983a-4598-a4b7-a9e5ba5a6a90' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--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.

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

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

Response:
204 no content