Open SidemenuDocs
Docs
Close Sidemenu

International Number Search & Orderinternational-number-search---order

Step 1: Query Requirementstep-1--query-requirement

Before searching or ordering phone numbers, you might want to understand the requirements of successfully ordering a number type in a particular market.

In this example, to successfully order local numbers in Germany, the user needs to provide all the enumerated information for admin review.

curl --location -g --request GET 'https://api.telnyx.com/v2/requirements
?filter[country_code]=DE
&filter[phone_number_type]=local
&filter[action]=ordering' \
--header 'Authorization: Bearer [REDACTED]' 
{
    "data": [
        {
            "action": "ordering",
            "country_code": "DE",
            "created_at": "2021-06-02T19:36:42Z",
            "id": "0ee8a0c9-c9dd-41e1-9ad6-e065affaf6d1",
            "locality": null,
            "phone_number_type": "local",
            "record_type": "requirement",
            "requirement_types": [
                {
                    "acceptance_criteria": {
                        "locality_limit": null,
                        "time_limit": null
                    },
                    "created_at": "2021-06-28T13:53:57Z",
                    "description": "Local Address in the same country as DID ordered(street, building number, postal code, city, and country)",
                    "example": "If you have ordered number in Spain, you must provide an address in Spain.",
                    "id": "0e84f7f9-d195-4d02-9873-9ac4b99c276d",
                    "name": "Local Address in the same country",
                    "record_type": "requirement_type",
                    "type": "address",
                    "updated_at": "2021-06-30T08:37:13Z"
                },
                {
                    "acceptance_criteria": {
                        "locality_limit": null,
                        "time_limit": null
                    },
                    "created_at": "2021-05-18T22:48:55Z",
                    "description": "Executed `Confirmation of local relationship to area code of allocated Local Service Numbers as defined in applicable Federal Network Agency (BNetzA) regulations on the structure and design of the number range for local numbers`. The document can be found here: https://tlyx.co/germany-registration.",
                    "example": "Executed Registration Form",
                    "id": "9e02e20d-167b-49f8-9b57-41495b538660",
                    "name": "Executed Registration Form",
                    "record_type": "requirement_type",
                    "type": "document",
                    "updated_at": "2021-05-18T22:48:55Z"
                },
                {
                    "acceptance_criteria": {
                        "locality_limit": null,
                        "time_limit": "Current and not expired"
                    },
                    "created_at": "2021-05-18T22:49:39Z",
                    "description": "In the case where the end user is a business, a certificate of business registration or incorporation demonstrating place of business is required. In the case where the end user is a person, a government issued ID, e.g. national ID card, permanent resident card, or passport, is required.",
                    "example": "National ID card, permanent resident card, passport, or business registration",
                    "id": "2f0dc1c2-34b4-4cf8-983c-da2b97be255a",
                    "name": "Proof of Identity",
                    "record_type": "requirement_type",
                    "type": "document",
                    "updated_at": "2021-05-18T22:49:39Z"
                },
                {
                    "acceptance_criteria": {
                        "locality_limit": null,
                        "time_limit": null
                    },
                    "created_at": "2021-04-30T15:48:58Z",
                    "description": "Name, business name, and contact phone numbers.",
                    "example": "Name, business name, and contact phone numbers.",
                    "id": "2708e569-696a-4fc7-9305-5fdb3eb9c7dd",
                    "name": "Contact Info",
                    "record_type": "requirement_type",
                    "type": "textual",
                    "updated_at": "2021-06-21T04:31:33Z"
                },
                {
                    "acceptance_criteria": {
                        "locality_limit": "Identical locality as the numbers desired",
                        "time_limit": "Within the last 6 months"
                    },
                    "created_at": "2021-05-18T22:49:22Z",
                    "description": "In the case where the end user is a business, office address with evidence of local activity (registration of the place of business with the relevant professional chambers, e.g. medical, bar, architects’ or pharmacists’ associations) is required. In the case where the end user is a person, a proof of residence such as utility bill or lease is required.",
                    "example": "Utility bill, lease, or other evidence of local activities",
                    "id": "6d3e2643-efaa-4bd3-8c31-77b6cda1d6a2",
                    "name": "Proof of Address (Local)",
                    "record_type": "requirement_type",
                    "type": "document",
                    "updated_at": "2021-06-30T08:41:50Z"
                }
            ],
            "updated_at": "2021-06-21T20:07:15Z"
        }
    ],
    "meta": {
        "page_number": 1,
        "page_size": 20,
        "total_pages": 1,
        "total_results": 1
    }
}

Step 2: Search for Desired Numbersstep-2--search-for-desired-numbers

Using the existing number searching V2 API or portal UI, you can search for the desired numbers. In this example, the user searches for 2 numbers in Nice, France and 2 numbers in Berlin.

Request 1

curl -X GET \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --globoff "https://api.telnyx.com/v2/available_phone_numbers
?filter[country_code]=fr
&filter[locality]=nice
&filter[limit]=2"
{
  "data": [
    {
      ...
      "phone_number": "+33422530985",
      ...
    },
    {
      ...
      "phone_number": "+33422530989",
      ...
    }
  ],
  "metadata": {
    "best_effort_results": 0,
    "total_results": 2
  },
  "url": "/v2/available_phone_numbers"
}

Request 2

curl -X GET \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --globoff "https://api.telnyx.com/v2/available_phone_numbers
?filter[country_code]=de
&filter[locality]=berlin
&filter[limit]=2"
{
  "data": [
    {
      ...
      "phone_number": "+493043514206",
      ...
    },
    {
      ...
      "phone_number": "+493042514214",
      ...
    }
  ],
  "metadata": {
    "best_effort_results": 0,
    "total_results": 2
  },
  "url": "/v2/available_phone_numbers"
}

You can also search for numbers in the Telnyx Portal. Simply click on "Numbers," then "Search & Buy Numbers." Select "Local Numbers" then choose the Region. Click "Search Numbers."

Step 3: Order Desired Numbersstep-3--order-desired-numbers

Using the existing number ordering V2 API, you can put in the order for the four numbers returned in the previous step.

curl -X POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{
    "phone_numbers": [
       {"phone_number": "+33422530985"},
       {"phone_number": "+33422530989"},
       {"phone_number": "+493043514206"},
       {"phone_number": "+493042514214"},
     ]
  }' \
  https://api.telnyx.com/v2/number_orders
{
  "data": {
    ...
    "id": "12ade33a-21c0-473b-b055-b3c836e1c292",
    ...
}

You will get a 200 OK response back with an order ID.

Step 4: Find the Sub Ordersstep-4--find-the-sub-orders

Because the order created previously contains numbers from two countries. They might have different requirements. Hence, they are grouped into logical sub orders for easier management subsequently.

There are two ways to get the sub orders of a number order.

Method 1: Include the filter[include_sub_orders]=true in the number order request.

curl -X POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{
    "phone_numbers": [
       {"phone_number": "+33422530985"},
       {"phone_number": "+33422530989"},
       {"phone_number": "+493043514206"},
       {"phone_number": "+493042514214"},
     ]
  }' \
  https://api.telnyx.com/v2/number_orders?filter[include_sub_orders]=true
{
    "data": {
        ...
        "sub_number_orders_ids": [
            "17f24e15-73af-4172-bcb5-75a26b3a2da6",
            "752588d9-3b95-4a7c-96e9-67c9a8259316",
            "d81e8932-5d09-4653-9cb2-d1667b721970"
        ],
        ...
    }
}

Method 2: Filter by your number order id

curl --location -g --request GET 'https://api.telnyx.com/v2/sub_number_orders
?filter[order_request_id]=4ea56fa4-3d82-4ed5-a141-d460d85dab53' \
--header 'Authorization: Bearer [REDACTED]' 
{
    "data": [
        {
            "phone_number_type": "local",
            "requirements_met": false,
            "order_request_id": "4ea56fa4-3d82-4ed5-a141-d460d85dab53",
            "user_id": "22",
            "id": "12bb9dc2-a1d6-4baa-9b0c-e37877162b74",
            "regulatory_requirements": [
                {
                    "record_type": "phone_number_regulatory_requirement",
                    "requirement_id": "0e84f7f9-d195-4d02-9873-9ac4b99c276d",
                    "field_type": "address"
                },
                {
                    "record_type": "phone_number_regulatory_requirement",
                    "requirement_id": "69f0eacf-d945-48a1-8625-034a02a5d9b5",
                    "field_type": "document"
                },
                {
                    "record_type": "phone_number_regulatory_requirement",
                    "requirement_id": "0ba49bfa-8a0b-4e38-95ba-f1291507fad4",
                    "field_type": "document"
                },
                {
                    "record_type": "phone_number_regulatory_requirement",
                    "requirement_id": "2708e569-696a-4fc7-9305-5fdb3eb9c7dd",
                    "field_type": "textual"
                },
                {
                    "record_type": "phone_number_regulatory_requirement",
                    "requirement_id": "6d3e2643-efaa-4bd3-8c31-77b6cda1d6a2",
                    "field_type": "document"
                }
            ],
            "phone_numbers_count": 1,
            "created_at": "2021-07-14T22:37:18.742757+00:00",
            "customer_reference": null,
            "country_code": "FR",
            "updated_at": "2021-07-14T22:37:18.742760+00:00",
            "record_type": "sub_number_order"
        },
        {
            "phone_number_type": "local",
            "requirements_met": false,
            "order_request_id": "4ea56fa4-3d82-4ed5-a141-d460d85dab53",
            "user_id": "22",
            "id": "d91d684f-3ccf-4615-aec7-b5e4b86250d6",
            "regulatory_requirements": [
                {
                    "record_type": "phone_number_regulatory_requirement",
                    "requirement_id": "0e84f7f9-d195-4d02-9873-9ac4b99c276d",
                    "field_type": "address"
                },
                {
                    "record_type": "phone_number_regulatory_requirement",
                    "requirement_id": "9e02e20d-167b-49f8-9b57-41495b538660",
                    "field_type": "document"
                },
                {
                    "record_type": "phone_number_regulatory_requirement",
                    "requirement_id": "2f0dc1c2-34b4-4cf8-983c-da2b97be255a",
                    "field_type": "document"
                },
                {
                    "record_type": "phone_number_regulatory_requirement",
                    "requirement_id": "2708e569-696a-4fc7-9305-5fdb3eb9c7dd",
                    "field_type": "textual"
                },
                {
                    "record_type": "phone_number_regulatory_requirement",
                    "requirement_id": "6d3e2643-efaa-4bd3-8c31-77b6cda1d6a2",
                    "field_type": "document"
                }
            ],
            "phone_numbers_count": 1,
            "created_at": "2021-07-14T22:37:18.713688+00:00",
            "customer_reference": null,
            "country_code": "DE",
            "updated_at": "2021-07-14T22:37:18.713691+00:00",
            "record_type": "sub_number_order"
        }
    ],
    "meta": {
        "total_pages": 1,
        "total_results": 2,
        "page_number": 1,
        "page_size": 25
    }
}

Step 5: Get the Human Readable Requirementstep-5--get-the-human-readable-requirement

curl --location --request GET 'https://api.telnyx.com/v2/requirement_types/9e02e20d-167b-49f8-9b57-41495b538660' \
--header 'Authorization: Bearer [REDACTED]' 
{
    "data": {
        "acceptance_criteria": {
            "locality_limit": null,
            "time_limit": null
        },
        "created_at": "2021-05-18T22:48:55Z",
        "description": "Executed `Confirmation of local relationship to area code of allocated Local Service Numbers as defined in applicable Federal Network Agency (BNetzA) regulations on the structure and design of the number range for local numbers`. The document can be found here: https://tlyx.co/germany-registration.",
        "example": "Executed Registration Form",
        "id": "9e02e20d-167b-49f8-9b57-41495b538660",
        "name": "Executed Registration Form",
        "record_type": "requirement_type",
        "type": "document",
        "updated_at": "2021-05-18T22:48:55Z"
    }
}

Step 6: Assign Values to Requirementstep-6--assign-values-to-requirement

After understanding the specific requirement, you can then assign values to each requirement, one by one, or all together.

curl 'https://api.telnyx.com/v2/sub_number_orders/d91d684f-3ccf-4615-aec7-b5e4b86250d6' \
  -X 'PATCH' \
  -H 'authorization: Bearer [REDACTED]' 
{
   "regulatory_requirements":[
      {
         "requirement_id":"0e84f7f9-d195-4d02-9873-9ac4b99c276d",
         "field_value":"1653278864371091174"
      },
      {
         "requirement_id":"9e02e20d-167b-49f8-9b57-41495b538660",
         "field_value":"20e790a4-e204-4396-b694-7ca48d582bfd"
      },
      {
         "requirement_id":"2f0dc1c2-34b4-4cf8-983c-da2b97be255a",
         "field_value":"20e790a4-e204-4396-b694-7ca48d582bfd"
      },
      {
         "requirement_id":"2708e569-696a-4fc7-9305-5fdb3eb9c7dd",
         "field_value":"Manny's Autoshop, +49356426158"
      },
      {
         "requirement_id":"6d3e2643-efaa-4bd3-8c31-77b6cda1d6a2",
         "field_value":"bd374c95-60f4-4441-aaa4-2e81edab5443"
      }
   ]
}

An Interlude --- Document APIan-interlude-----document-api

If you have not previously uploaded documents, you will need to add new documents to attach to the requirements. Documented here is the API to do that.

Docs API

curl --location --request POST 'https://api.telnyx.com/v2/documents' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer [REDACTED]' \
--data-raw '{
    "url": "http://pages.cs.wisc.edu/~remzi/OSTEP/threads-sema.pdf"
}'

Or upload as 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.

Step 7: Communicating with Adminstep-7--communicating-with-admin

This allows you to communicate with Telnyx admins regarding regulatory requirements on your sub orders.

curl -X POST 'https://api.telnyx.com/v2/comments' 
{
   "body":"How can I get a Registration Form?",
   "comment_record_type":"sub_number_order",
   "comment_record_id":"d91d684f-3ccf-4615-aec7-b5e4b86250d6"
}

You can also see all comments related to your specific suborder.

curl -X GET \
  'https://api.telnyx.com/v2/sub_number_orders/32ade33a-c836-36e1-b055-b3c836e1c292/comments' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ' \
{
  "data": [
    {
      "id": "dc8e4d67-33a0-4cbb-af74-7b58f05bd494",
      "body": "string",
      "commenter": "employee@telnyx.com",
      "commenter_type": "admin",
      "read_at": "2018-01-01T00:00:00.000000Z",
      "created_at": "2018-01-01T00:00:00.000000Z",
      "updated_at": "2018-01-01T00:00:00.000000Z",
      "record_type": "sub_number_order_comment"
    }
  ],
  "meta": {
    "total_pages": 3,
    "total_results": 55,
    "page_number": 2,
    "page_size": 25
  }
}

Was this page helpful?