Quickstart - International Number Search and Order
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.
Request Sample
NoteDon't forget to update
YOUR_API_KEY
here.
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 YOUR_API_KEY'
{
"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 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 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 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 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"
}
}
Requirement Types
There are four possible field_type
(from GET v2/sub_number_orders
) or requirement_type
(from GET v2/requirement_types/{{id}}
) values:
textual
address
document
action
Each type has different rules for fulfilling the requirement.
Textual type
To fulfill a textual
requirement, any string can be provided. Assuming it complies with the requirement's acceptance_criteria
.
Address type
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. "312 W Superior St, Chicago, IL, 60654") to fulfill the requirement. You must create the address, and pass the address id
as the field_value
.
Document type
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 providing the URL to a publicly hosted document:
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.
Action type
An action
requirement is unique, and very rare. Please see our separate developer guide to learn more about how to handle action
requirement types.
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]'
{
"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"
}
]
}
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'
{
"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
}
}