Number Orders

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

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

Copy

Copied

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: After pasting the above content, Kindly check and remove any new line added

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.

Copy

Copied

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

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

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.

Copy

Copied

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

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

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

Retrieve All Orders

Copy

Copied

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"

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

Sample Response

Copy

Copied

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

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

Retrieve An Order

Copy

Copied

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"

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

Sample Response

Copy

Copied

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

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