Voice Self-Service for your growing business needs
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
Params:
| 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). |
Responses:
| 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" "https://api.nimblevox.com/number/npa?digits={digits}?apiKey={apiKey}&max=10"
Retrieve available numbers by npanxx:
curl -H "Accept: application/xml" "https://api.nimblevox.com/number/npanxx?digits={digits}?apiKey={apiKey}&max=5"
Retrieve available numbers by state:
curl -H "Accept: application/xml" "https://api.nimblevox.com/number/state?state={state}&apiKey={apiKey}"
Retrieve available toll free numbers:
curl -H "Accept: application/json" "https://api.nimblevox.com/number/tollfree?apiKey={apiKey}&max=20"
Example XML Response:
<numbers>
<number id='4027774440' href='api/number/4027774440'>
<numberType>LOCAL</numberType>
<smsEnabled/>
<smsUrl/>
<projectName/>
</number>
<number id='4027774441' href='api/number/4027704441'>
<numberType>LOCAL</numberType>
<smsEnabled/>
<smsUrl/>
<projectName/>
</number>
</numbers>
Example JSON Response:
{"numbers":[{"id":8884445555,"href":"api/number/8884445555","numberType":"TOLL_FREE","smsEnabled":null,"smsUrl":null,"projectName":null"},{"id":8884446666,"href":"api/number/8884446666","numberType":"TOLL_FREE","smsEnabled":null,"smsUrl":null,"projectName":null"}]}
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. |
