Quickstart - International Number Search

Step 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.

Copy
Copied
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]'

Note: After pasting the above content, Kindly check and remove any new line added

Copy
Copied
{
    "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
    }
}

Note: After pasting the above content, Kindly check and remove any new line added

Step 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

Copy
Copied
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"

Note: After pasting the above content, Kindly check and remove any new line added

Copy
Copied
{
  "data": [
    {
      ...
      "phone_number": "+33422530985",
      ...
    },
    {
      ...
      "phone_number": "+33422530989",
      ...
    }
  ],
  "metadata": {
    "best_effort_results": 0,
    "total_results": 2
  },
  "url": "/v2/available_phone_numbers"
}

Note: After pasting the above content, Kindly check and remove any new line added

Request 2

Copy
Copied
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"

Note: After pasting the above content, Kindly check and remove any new line added

Copy
Copied
{
  "data": [
    {
      ...
      "phone_number": "+493043514206",
      ...
    },
    {
      ...
      "phone_number": "+493042514214",
      ...
    }
  ],
  "metadata": {
    "best_effort_results": 0,
    "total_results": 2
  },
  "url": "/v2/available_phone_numbers"
}

Note: After pasting the above content, Kindly check and remove any new line added

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 Numbers

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

Copy
Copied
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

Note: After pasting the above content, Kindly check and remove any new line added

Copy
Copied
{
  "data": {
    ...
    "id": "12ade33a-21c0-473b-b055-b3c836e1c292",
    ...
}

Note: After pasting the above content, Kindly check and remove any new line added

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

Step 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.

Copy
Copied
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

Note: After pasting the above content, Kindly check and remove any new line added

Copy
Copied
{
    "data": {
        ...
        "sub_number_orders_ids": [
            "17f24e15-73af-4172-bcb5-75a26b3a2da6",
            "752588d9-3b95-4a7c-96e9-67c9a8259316",
            "d81e8932-5d09-4653-9cb2-d1667b721970"
        ],
        ...
    }
}

Note: After pasting the above content, Kindly check and remove any new line added

Method 2: Filter by your number order id

Copy
Copied
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]'

Note: After pasting the above content, Kindly check and remove any new line added

Copy
Copied
{
    "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
    }
}

Note: After pasting the above content, Kindly check and remove any new line added

Step 5: Get the Human Readable Requirement

Copy
Copied
curl --location --request GET 'https://api.telnyx.com/v2/requirement_types/9e02e20d-167b-49f8-9b57-41495b538660' \
--header 'Authorization: Bearer [REDACTED]'

Note: After pasting the above content, Kindly check and remove any new line added

Copy
Copied
{
    "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"
    }
}

Note: After pasting the above content, Kindly check and remove any new line added

Step 6: Assign Values to Requirement

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

Copy
Copied
curl 'https://api.telnyx.com/v2/sub_number_orders/d91d684f-3ccf-4615-aec7-b5e4b86250d6' \
  -X 'PATCH' \
  -H 'authorization: Bearer [REDACTED]'

Note: After pasting the above content, Kindly check and remove any new line added

Copy
Copied
{
   "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"
      }
   ]
}

Note: After pasting the above content, Kindly check and remove any new line added

An 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

Copy
Copied
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"
}'

Note: After pasting the above content, Kindly check and remove any new line added

Or upload as multipart

Copy
Copied
curl --location --request POST 'https://api.telnyx.com/v2/documents' \
--header 'Content-Type: multipart/form-data' \
--header 'Authorization: Bearer [REDACTED]' \
--form '[email protected]/Users/xd/Downloads/threads-bugs.pdf'

Note: After pasting the above content, Kindly check and remove any new line added

Or upload as a base64 encoded file

Copy
Copied
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}"
}'

Note: After pasting the above content, Kindly check and remove any new line added

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 Admin

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

Copy
Copied
curl -X POST 'https://api.telnyx.com/v2/comments'

Note: After pasting the above content, Kindly check and remove any new line added

Copy
Copied
{
   "body":"How can I get a Registration Form?",
   "comment_record_type":"sub_number_order",
   "comment_record_id":"d91d684f-3ccf-4615-aec7-b5e4b86250d6"
}

Note: After pasting the above content, Kindly check and remove any new line added

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

Copy
Copied
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 ' \

Note: After pasting the above content, Kindly check and remove any new line added

Copy
Copied
{
  "data": [
    {
      "id": "dc8e4d67-33a0-4cbb-af74-7b58f05bd494",
      "body": "string",
      "commenter": "[email protected]",
      "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
  }
}

Note: After pasting the above content, Kindly check and remove any new line added