Quickstart - International Number Search and Order

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.

Note

Don'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
    }
}

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

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.

Note: If you are planning on ordering a phone number in one of the following countries, you will need to include a Requirement Group in your order request:

• CH (Switzerland)
• DK (Denmark)
• IT (Italy)
• NO (Norway)
• PT (Portugal)
• SE (Sweden)

Please see this developer guide for more details.

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

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

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.

To fulfill a textual requirement, any string can be provided. Assuming it complies 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. "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.

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.

An action requirement is unique, and very rare. Please see our separate developer guide to learn more about how to handle action requirement types.

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

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