Maximize productivity with personalized, automated calling

Voice Self-Service for your growing business needs

Retrieve Available Numbers

The number API allows you to retrieve a list of phone numbers available for assignment to your account.

Set header Accept (optional) = the expected response format

  • application/xml (default)
  • application/json


apiKey Required The apiKey associates the API call with your account.
state Required The two-character state. Only phone numbers assigned to this state are returned. Note: This is only required when searching by state.
digits Required The first 3 (searching by npa) or 6 (searching by npanxx) digits of the phone number. Only phone numbers that start with the entered digits are returned. Note: This is only required when searching by npa or npanxx.
max Optional Limits the number of phone numbers returned (default is 10).


200 OK The message was successfully sent
400 Bad Request Invalid search digits
401 Unauthorized API was not authorized
404 Not Found No available numbers found with the requested state/digits
406 Not Acceptable Supported response formats are json and xml
500 Internal Server Error

Example CURL Commands:
Copy the command and replace with your {apiKey}, the required params and, if desired, the optional param.
Retrieve available numbers by npa:

curl -H "Accept: application/xml" "{digits}?apiKey={apiKey}&max=10"

Retrieve available numbers by npanxx:

curl -H "Accept: application/xml" "{digits}?apiKey={apiKey}&max=5"

Retrieve available numbers by state:

curl -H "Accept: application/xml" "{state}&apiKey={apiKey}"

Retrieve available toll free numbers:

curl -H "Accept: application/json" "{apiKey}&max=20"

Example XML Response:

   <number id='4027774440' href='api/number/4027774440'>
   <number id='4027774441' href='api/number/4027704441'>

Example JSON Response:


Response Field Definitions:

Element Name Description
id The available number.
href The location of the number Resource.
numberType The type of number: LOCAL, TOLL_FREE or SIP.
smsEnabled Whether or not SMS is enabled for the number: true or false
smsUrl The URL to receive the SMS at for the requested number, if configured.
projectName The name of the nimblevox Blast build project assigned to the number, if configured.