Buy a number

To make and receive calls with the Voice API, and to receive messages using the SMS API, you need to buy a number to use with the API.

You can purchase numbers using the Dashboard in the Your Numbers section, or programmatically.

Search for a number

curl "https://rest.nexmo.com/number/search/API_KEY/API_SECRET/COUNTRY?pattern={pattern}&search_pattern={search_pattern}&features={features}&index={index}&size={size}"
import nexmo

client = nexmo.Client(key=API_KEY, secret=API_SECRET)
client.get_available_numbers("FR")
client.get_available_numbers("BR", {"features": "SMS"})
client.get_available_numbers("FR", {"pattern": "007", "search_pattern": 1})
client.get_available_numbers("IT", params)
require 'nexmo'

client = Nexmo::Client.new(api_key: API_KEY, api_secret: API_SECRET)
client.numbers.search(country: 'FR')
client.numbers.search(country: 'BR', features: "SMS")
client.numbers.search(country: 'FR', pattern: "007", search_pattern: 1)
> nexmo number:search US
12057200555
12069396555
12069396555
12155961555

> nexmo number:search NL --sms --pattern *007 --verbose
msisdn      | country | cost | type       | features
-----------------------------------------------------
31655551007 | NL      | 3.00 | mobile-lvn | VOICE,SMS
31655552007 | NL      | 3.00 | mobile-lvn | VOICE,SMS
31655553007 | NL      | 3.00 | mobile-lvn | VOICE,SMS

See the Nexmo CLI documentation for details on arguments.

Buy a number

curl -X POST "https://rest.nexmo.com/number/buy/API_KEY/API_SECRET/COUNTRY/MSISDN"
import nexmo

client = nexmo.Client(key=API_KEY, secret=API_SECRET)
client.buy_number({"country": "GB", "msisdn": "447700900000"})
require 'nexmo'

client = Nexmo::Client.new(api_key: API_KEY, api_secret: API_SECRET)
client.numbers.buy(country: "GB", msisdn: "447700900000")
> nexmo number:buy 12069396555
Buying 12069396555\. This operation will charge your account.

Please type "confirm" to continue: confirm

Number purchased

> nexmo number:buy US *555
Buying 12069396555\. This operation will charge your account.

Please type "confirm" to continue: confirm

Number purchased: 12069396555

> nexmo number:buy 12069396555 --confirm
Number purchased: 12069396555