On this page

VoiceCountry Resource

The Pricing Voice resource provides an API to pull real-time, account-specific pricing for Twilio's Programmable Voice product.

Prices can be retrieved at a country level or for a specific phone number via the Pricing Voice Numbers resource.

You may also wish to check out our Pricing API resources for Twilio's Messaging and Phone Number products.

(information)

Info

Looking for details on pricing for Twilio products? Check out Twilio's pricing page.

This resource represents prices to make voice calls to phone numbers in a given country, organized by phone number prefix (OutboundPrefixPriceWithOrigin), and the prices to receive voice calls on Twilio phone numbers in this country, organized by phone number type (InboundCallPrices).

Country Properties

Property nameTypeRequiredDescriptionChild properties

countrystring

Optional

Not PII

The name of the country.

iso_countrystring<iso-country-code>

Optional

Not PII

The ISO country code.

urlstring<uri>

Optional

Not PII

The absolute URL of the resource.

outbound_prefix_pricesarray[object<outbound-prefix-price-with-origin>]

Optional

Not PII

The list of OutboundPrefixPriceWithOrigin records.

Show child properties for outbound_prefix_prices

inbound_call_pricesarray[object<inbound-call-price>]

Optional

Not PII

The list of InboundCallPrice records.

Show child properties for inbound_call_prices

price_unitstring<currency>

Optional

Not PII

The currency in which prices are measured, specified in ISO 4127 format (e.g. usd, eur, jpy).

OutboundPrefixPrices record

Property	Description
DestinationPrefixes	Set of destination phone number prefixes for the requested country with the same pricing
OriginationPrefixes	Set of origination phone number prefixes for the requested country with the same pricing. Valid set elements include specific prefixes, `ALL` (representing the entire set of all valid prefixes), or `ROW` (representing the rest-of-world, which is the set of remaining prefixes that aren't specifically listed)
FriendlyName	Descriptive text for this set of prefixes
BasePrice	The retail price per minute to make a call to numbers matching this prefix list
CurrentPrice	The current price per minute (which accounts for any volume or custom price discounts) to make a call to numbers matching this prefix list.

InboundCallPrices record

Property	Description
NumberType	The phone number type, either `local`, `mobile`, `national`, or `toll free`
BasePrice	The retail price per minute to receive a call to this phone number type.
CurrentPrice	The current price per minute (which accounts for any volume or custom price discounts) to receive a call to this phone number type.

Fetch a VoiceCountry resource

GET https://pricing.twilio.com/v2/Voice/Countries/{IsoCountry}

Where {IsoCountry} is the ISO 3166-1 alpha-2 format country code

Path parameters

Property nameTypeRequiredPIIDescription

IsoCountrystring<iso-country-code>required

Not PII

The ISO country code of the origin-based voice pricing information to fetch.

Fetch a VoiceCountry resource

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function fetchVoiceCountry() {
11  const country = await client.pricing.v2.voice.countries("BB").fetch();
12
13  console.log(country.country);
14}
15
16fetchVoiceCountry();

Output

1{
2  "country": "United States",
3  "inbound_call_prices": [
4    {
5      "base_price": "0.0085",
6      "current_price": "0.0085",
7      "number_type": "local"
8    },
9    {
10      "base_price": "0.022",
11      "current_price": "0.022",
12      "number_type": "toll free"
13    }
14  ],
15  "iso_country": "BB",
16  "outbound_prefix_prices": [
17    {
18      "base_price": "0.090",
19      "current_price": "0.090",
20      "destination_prefixes": [
21        "1907"
22      ],
23      "friendly_name": "Programmable Outbound Minute - United States - Alaska",
24      "origination_prefixes": [
25        "ALL"
26      ]
27    },
28    {
29      "base_price": "0.013",
30      "current_price": "0.013",
31      "destination_prefixes": [
32        "1808"
33      ],
34      "friendly_name": "Programmable Outbound Minute - United States - Hawaii",
35      "origination_prefixes": [
36        "ALL"
37      ]
38    },
39    {
40      "base_price": "0.013",
41      "current_price": "0.013",
42      "destination_prefixes": [
43        "1800",
44        "1844",
45        "1855",
46        "1866",
47        "1877",
48        "1888"
49      ],
50      "friendly_name": "Programmable Outbound Minute - United States & Canada - Toll Free",
51      "origination_prefixes": [
52        "ALL"
53      ]
54    },
55    {
56      "base_price": "0.013",
57      "current_price": "0.013",
58      "destination_prefixes": [
59        "1"
60      ],
61      "friendly_name": "Programmable Outbound Minute - United States & Canada",
62      "origination_prefixes": [
63        "ALL"
64      ]
65    }
66  ],
67  "price_unit": "USD",
68  "url": "https://pricing.twilio.com/v2/Voice/Countries/US"
69}

Read multiple VoiceCountry resources

GET https://pricing.twilio.com/v2/Voice/Countries

Query parameters

Property nameTypeRequiredPIIDescription

PageSizeinteger

Optional

Not PII

How many resources to return in each list page. The default is 50, and the maximum is 1000.

Minimum: 1Maximum: 1000

Pageinteger

Optional

Not PII

The page index. This value is simply for client state.

Minimum: 0

PageTokenstring

Optional

Not PII

The page token. This is provided by the API.

List all VoiceCountry resources

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function listVoiceCountry() {
11  const countries = await client.pricing.v2.voice.countries.list({ limit: 20 });
12
13  countries.forEach((c) => console.log(c.country));
14}
15
16listVoiceCountry();

Output

1{
2  "countries": [
3    {
4      "country": "Andorra",
5      "iso_country": "AD",
6      "url": "https://pricing.twilio.com/v2/Voice/Countries/AD"
7    }
8  ],
9  "meta": {
10    "first_page_url": "https://pricing.twilio.com/v2/Voice/Countries?PageSize=50&Page=0",
11    "key": "countries",
12    "next_page_url": null,
13    "page": 0,
14    "page_size": 50,
15    "previous_page_url": null,
16    "url": "https://pricing.twilio.com/v2/Voice/Countries?PageSize=50&Page=0"
17  }
18}