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.
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
{
"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
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
{
"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
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
{
"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.
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
{
"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.
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
{
"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
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
{
"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
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
{
"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.
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
{
"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.
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
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'
Note: After pasting the above content, Kindly check and remove any new line added
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}"
}'
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.
curl -X POST 'https://api.telnyx.com/v2/comments'
Note: After pasting the above content, Kindly check and remove any new line added
{
"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.
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
{
"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