Quickstart - Number Orders

cURL

With Telnyx, you can purchase numbers from 15,000+ rate centers and 40 different countries using our RESTful API.

Follow this guide to order US/CA numbers, or any number that begins with the country code +1. See here to check if that includes the country/territory you desire. If you're looking for any other international numbers, there are some additional requirements that we cover in depth in our International Number Search & Order guide.

Note
If you're trying to figure out how to acquire your API key, take a look at the Development Environment Setup guide. It will also show you how to set up a Telnyx SDK if applicable.

Order a number

To see if a number is available, you'll need to carry out a search for that sepcific number. Once you have checked that, you'll need to purchase it.

Note
Don't forget to update YOUR_API_KEY here.

curl -X POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{
    "phone_numbers": [{"phone_number": "+18665552368"}]
  }' \
  https://api.telnyx.com/v2/number_orders

Retrieve all orders

curl -X GET \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  "https://api.telnyx.com/v2/number_orders"

Sample response

{
  "data": [
    {
      "connection_id": null,
      "created_at": "2018-11-19T15:55:00.319129+00:00",
      "customer_reference": null,
      "id": "123-543-54321-54321",
      "messaging_profile_id": null,
      "phone_numbers_count": 1,
      "record_type": "number_order",
      "requirements_met": true,
      "status": "success",
      "updated_at": "2018-11-19T15:55:00.319129+00:00"
    },
    {
      "connection_id": null,
      "created_at": "2018-10-31T16:42:34.518340+00:00",
      "customer_reference": null,
      "id": "4567-45678-45678-5743",
      "messaging_profile_id": null,
      "phone_numbers_count": 5,
      "record_type": "number_order",
      "requirements_met": true,
      "status": "pending",
      "updated_at": "2018-10-31T16:42:34.518340+00:00"
    },
  ],
  "meta": {
    "page_number": 1,
    "page_size": 25,
    "total_pages": 1,
    "total_results": 2
  },
  "url": "/v2/number_orders"
}

Retrieve An Order

curl -X GET \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  "https://api.telnyx.com/v2/number_orders/{number_order_id}"

Sample response

{
  "connection_id": null,
  "created_at": "2018-11-19T15:55:00.319129+00:00",
  "customer_reference": null,
  "id": "1234-56789-6789-5678",
  "messaging_profile_id": null,
  "phone_numbers": [
    {
      "id": "123cvgbh-fvgbhn-fvgbh-vgbh",
      "phone_number": "+15555555555",
      "record_type": "number_order_phone_number",
      "regulatory_requirements": [],
      "requirements_met": true,
      "status": "success"
    }
  ],
  "phone_numbers_count": 1,
  "record_type": "number_order",
  "requirements_met": true,
  "status": "success",
  "updated_at": "2018-11-19T15:55:00.319129+00:00"
}

Need some extra help?

Our support team are on hand 24/7/365, click the chat icon in the lower right hand corner to start chatting!

Python

With Telnyx, you can purchase numbers from 15,000+ rate centers and 40 different countries using our RESTful API.

If you're trying to figure out how to acquire your API key, take a look at the Development Environment Setup guide. It will also show you how to set up a Telnyx SDK if applicable.

Order a number

To see if a number is available, you'll need to carry out a search for that sepcific number. Once you have checked that, you'll need to purchase it.

import telnyx
telnyx.api_key = "YOUR_API_KEY"

telnyx.NumberOrder.create(
  phone_numbers=[{"phone_number": "+18665552368"}]
)

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

Retrieve all orders

import telnyx
telnyx.api_key = "YOUR_API_KEY"

telnyx.NumberOrder.list(filter={"phone_numbers.phone_number": ["+18665552368"]})

Sample response

{
  "data": [
    {
      "connection_id": null,
      "created_at": "2018-11-19T15:55:00.319129+00:00",
      "customer_reference": null,
      "id": "123-543-54321-54321",
      "messaging_profile_id": null,
      "phone_numbers_count": 1,
      "record_type": "number_order",
      "requirements_met": true,
      "status": "success",
      "updated_at": "2018-11-19T15:55:00.319129+00:00"
    },
    {
      "connection_id": null,
      "created_at": "2018-10-31T16:42:34.518340+00:00",
      "customer_reference": null,
      "id": "4567-45678-45678-5743",
      "messaging_profile_id": null,
      "phone_numbers_count": 5,
      "record_type": "number_order",
      "requirements_met": true,
      "status": "pending",
      "updated_at": "2018-10-31T16:42:34.518340+00:00"
    },
  ],
  "meta": {
    "page_number": 1,
    "page_size": 25,
    "total_pages": 1,
    "total_results": 2
  },
  "url": "/v2/number_orders"
}

Retrieve an order

import telnyx
telnyx.api_key = "YOUR_API_KEY"

telnyx.NumberOrder.retrieve("uuid")

Sample response

{
  "connection_id": null,
  "created_at": "2018-11-19T15:55:00.319129+00:00",
  "customer_reference": null,
  "id": "1234-56789-6789-5678",
  "messaging_profile_id": null,
  "phone_numbers": [
    {
      "id": "123cvgbh-fvgbhn-fvgbh-vgbh",
      "phone_number": "+15555555555",
      "record_type": "number_order_phone_number",
      "regulatory_requirements": [],
      "requirements_met": true,
      "status": "success"
    }
  ],
  "phone_numbers_count": 1,
  "record_type": "number_order",
  "requirements_met": true,
  "status": "success",
  "updated_at": "2018-11-19T15:55:00.319129+00:00"
}

Need some extra help?

Our support team are on hand 24/7/365, click the chat icon in the lower right hand corner to start chatting!

Node

With Telnyx, you can purchase numbers from 15,000+ rate centers and 40 different countries using our RESTful API.

If you're trying to figure out how to acquire your API key, take a look at the Development Environment Setup guide. It will also show you how to set up a Telnyx SDK if applicable.

Order a number

To see if a number is available, you'll need to carry out a search for that sepcific number. Once you have checked that, you'll need to purchase it.

import Telnyx from 'telnyx';

const { data: numberOrder } = await telnyx.numberOrders.create({
  phone_numbers:[{"phone_number": "+18665552368"}]
});

console.log(numberOrder);

Retrieve all orders

import Telnyx from 'telnyx';

const telnyx = new Telnyx("YOUR_API_KEY");

const { data: ordersList } = await telnyx.numberOrders.list({
    filter:{"phone_numbers.phone_number": ["+18665552368"]}
});

console.log(ordersList);

Sample response

{
  "data": [
    {
      "connection_id": null,
      "created_at": "2018-11-19T15:55:00.319129+00:00",
      "customer_reference": null,
      "id": "123-543-54321-54321",
      "messaging_profile_id": null,
      "phone_numbers_count": 1,
      "record_type": "number_order",
      "requirements_met": true,
      "status": "success",
      "updated_at": "2018-11-19T15:55:00.319129+00:00"
    },
    {
      "connection_id": null,
      "created_at": "2018-10-31T16:42:34.518340+00:00",
      "customer_reference": null,
      "id": "4567-45678-45678-5743",
      "messaging_profile_id": null,
      "phone_numbers_count": 5,
      "record_type": "number_order",
      "requirements_met": true,
      "status": "pending",
      "updated_at": "2018-10-31T16:42:34.518340+00:00"
    },
  ],
  "meta": {
    "page_number": 1,
    "page_size": 25,
    "total_pages": 1,
    "total_results": 2
  },
  "url": "/v2/number_orders"
}

Retrieve an order

import Telnyx from 'telnyx';

const telnyx = new Telnyx("YOUR_API_KEY");

const { data: numberOrder } = await telnyx.numberOrders.retrieve("uuid");

console.log(numberOrder);

Sample response

{
  "connection_id": null,
  "created_at": "2018-11-19T15:55:00.319129+00:00",
  "customer_reference": null,
  "id": "1234-56789-6789-5678",
  "messaging_profile_id": null,
  "phone_numbers": [
    {
      "id": "123cvgbh-fvgbhn-fvgbh-vgbh",
      "phone_number": "+15555555555",
      "record_type": "number_order_phone_number",
      "regulatory_requirements": [],
      "requirements_met": true,
      "status": "success"
    }
  ],
  "phone_numbers_count": 1,
  "record_type": "number_order",
  "requirements_met": true,
  "status": "success",
  "updated_at": "2018-11-19T15:55:00.319129+00:00"
}

Need some extra help?

Our support team are on hand 24/7/365, click the chat icon in the lower right hand corner to start chatting!

.NET

With Telnyx, you can purchase numbers from 15,000+ rate centers and 40 different countries using our RESTful API.

If you're trying to figure out how to acquire your API key, take a look at the Development Environment Setup guide. It will also show you how to set up a Telnyx SDK if applicable.

Order a number

To see if a number is available, you'll need to carry out a search for that sepcific number. Once you have checked that, you'll need to purchase it.

using System;
using Telnyx.net.Services.VerifyAPI;
private static string TELNYX_API_KEY ="TELNYX_API_KEY";

Telnyx.TelnyxConfiguration.SetApiKey(TELNYX_API_KEY);
VerificationService verifyService = new VerificationService();

static void NumberSearch ()  {
    var numberSearchService = new Telnyx.NumberSearchService();
    var numberSearchOptions = new Telnyx.NumberSearchOptions(){
        CountryCode = "USA",
        AdministrativeArea = "IL",
        NumberType = "toll-free",
        NationalDestinationCode = "877",
        Limit = 2
    };
    numberSearchService.List(numberSearchOptions);

Retrieve all orders

require "telnyx"

Telnyx.api_key = "YOUR_API_KEY"

Telnyx::NumberOrder.list(
    filter:{phone_numbers.phone_number: ["+18665552368"]}
)

Sample response

{
  "data": [
    {
      "connection_id": null,
      "created_at": "2018-11-19T15:55:00.319129+00:00",
      "customer_reference": null,
      "id": "123-543-54321-54321",
      "messaging_profile_id": null,
      "phone_numbers_count": 1,
      "record_type": "number_order",
      "requirements_met": true,
      "status": "success",
      "updated_at": "2018-11-19T15:55:00.319129+00:00"
    },
    {
      "connection_id": null,
      "created_at": "2018-10-31T16:42:34.518340+00:00",
      "customer_reference": null,
      "id": "4567-45678-45678-5743",
      "messaging_profile_id": null,
      "phone_numbers_count": 5,
      "record_type": "number_order",
      "requirements_met": true,
      "status": "pending",
      "updated_at": "2018-10-31T16:42:34.518340+00:00"
    },
  ],
  "meta": {
    "page_number": 1,
    "page_size": 25,
    "total_pages": 1,
    "total_results": 2
  },
  "url": "/v2/number_orders"
}

Retrieve an order

require "telnyx"

Telnyx.api_key = "YOUR_API_KEY"

Telnyx::NumberOrder.retrieve("uuid")

Sample response

{
  "connection_id": null,
  "created_at": "2018-11-19T15:55:00.319129+00:00",
  "customer_reference": null,
  "id": "1234-56789-6789-5678",
  "messaging_profile_id": null,
  "phone_numbers": [
    {
      "id": "123cvgbh-fvgbhn-fvgbh-vgbh",
      "phone_number": "+15555555555",
      "record_type": "number_order_phone_number",
      "regulatory_requirements": [],
      "requirements_met": true,
      "status": "success"
    }
  ],
  "phone_numbers_count": 1,
  "record_type": "number_order",
  "requirements_met": true,
  "status": "success",
  "updated_at": "2018-11-19T15:55:00.319129+00:00"
}

Need some extra help?

Our support team are on hand 24/7/365, click the chat icon in the lower right hand corner to start chatting!

Ruby

With Telnyx, you can purchase numbers from 15,000+ rate centers and 40 different countries using our RESTful API.

If you're trying to figure out how to acquire your API key, take a look at the Development Environment Setup guide. It will also show you how to set up a Telnyx SDK if applicable.

Order a number

To see if a number is available, you'll need to carry out a search for that sepcific number. Once you have checked that, you'll need to purchase it.

require "telnyx"

Telnyx.api_key = "YOUR_API_KEY"

Telnyx::NumberOrder.create(
    phone_numbers:[{phone_number: "+18665552368"}]
)

Retrieve all orders

require "telnyx"

Telnyx.api_key = "YOUR_API_KEY"

Telnyx::NumberOrder.list(
    filter:{phone_numbers.phone_number: ["+18665552368"]}
)

Sample response

{
  "connection_id": null,
  "created_at": "2018-11-19T15:55:00.319129+00:00",
  "customer_reference": null,
  "id": "1234-56789-6789-5678",
  "messaging_profile_id": null,
  "phone_numbers": [
    {
      "id": "123cvgbh-fvgbhn-fvgbh-vgbh",
      "phone_number": "+15555555555",
      "record_type": "number_order_phone_number",
      "regulatory_requirements": [],
      "requirements_met": true,
      "status": "success"
    }
  ],
  "phone_numbers_count": 1,
  "record_type": "number_order",
  "requirements_met": true,
  "status": "success",
  "updated_at": "2018-11-19T15:55:00.319129+00:00"
}

Need some extra help?

Our support team are on hand 24/7/365, click the chat icon in the lower right hand corner to start chatting!