This is the current API V1 documentation. Explore our API V2 if you’d like to test new features.

Open SidemenuDocs
Docs
Close Sidemenu
Choose:
cURLPython
cURLPython

Number Ordersnumber-orders

You can purchase numbers from 15,000+ rate centers and 40 different countries via our RESTful APIAPI.

Order a Numberorder-a-number

First, you'll need to search for the number to make sure it's available. Once you've done this, you're ready to purchase.

curl -X POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "x-api-token: API_TOKEN" \
  --header "x-api-user: API_USER" \
  --data '{"requested_numbers":"+18728880010"}' \
  "https://api.telnyx.com/origination/number_orders"

Note: Just after the purchase, the order will be in pending status until it's been confirmed.

Send requested_numbers_with_metadata when ordering specific numbers seen in recent search results. The metadata that you send is meant to satisfy local requirements associated with numbers purchased. If no local requirements exist, as is the case for US numbers, you can simply omit everything but the numbers themselves.

{
  "requested_numbers_with_metadata": [
    { "number": "+13035551111", "address_id": "1" },
    { "number": "+13035551112", "address_id": "1" },
    { "number": "+13035551113", "address_id": "2" }
  ]
}

Send requested_inexplicit_numbers when ordering numbers from inexplicit search results. You'll pass along the inexplicit search results of the numbers you wish to purchase, plus a quantity and, optionally, an address_id. The address_id is used to satisfy number ownership verification requirements in some localities. When provided, it must reference an address record on your account. That address will be passed along to the local numbering authorities when required.

{
  "requested_inexplicit_numbers": [
    "quantity": 100,
    "address_id": "123",
    "national_destination_code": "9",
    "country_iso": "FI",
    "region_name": "Helsinki",
    "region_type": "city"
  ]
}

Congrats, you’ve just purchased your first phone number using the Telnyx API.

Retrieve All Ordersretrieve-all-orders

curl -X GET \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "x-api-user: YOUR_API_ACCESS_KEY" \
  --header "x-api-token: YOUR_API_TOKEN" \
  "https://api.telnyx.com/origination/number_orders"

Sample Responsesample-response

[
  {
    "date_due": "2019-04-19T21:58:03.784627+00:00",
    "requirements_met": true,
    "date_created": "2019-04-09T21:58:03.784627+00:00",
    "order_request_id": "123-543-54321-54321",
    "numbers_count": 10
  },
  {
    "date_due": "2019-01-12T09:26:01.883388+00:00",
    "requirements_met": true,
    "date_created": "2019-01-02T09:26:01.883388+00:00",
    "order_request_id": "4567-45678-45678-5743",
    "numbers_count": 5
  }
]

Retrieve An Orderretrieve-an-order

curl -X GET \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "x-api-user: YOUR_API_ACCESS_KEY" \
  --header "x-api-token: YOUR_API_TOKEN" \
  "https://api.telnyx.com/origination/1234-56789-6789-5678"

Sample Responsesample-response

{
  "requested_numbers": [
    {
      "requirements": null,
      "allocated": true,
      "status": "success",
      "customer_phone": null,
      "requirements_met": true,
      "number": "+15555555555",
      "tax_id": null,
      "customer_name": null,
      "provided_documents": {
        "reg_form_file_ids": [],
        "identification_file_ids": [],
        "address_proof_file_ids": []
      }
    }
  ],
  "date_due": "2019-01-12T09:26:01.883388+00:00",
  "requirements_met": true,
  "order_request_id": "1234-56789-6789-5678",
  "numbers_count": 1,
  "date_created": "2019-01-02T09:26:01.883388+00:00"
}