Voice Self-Service for your growing business needs
The number API allows you to request (order) a phone number for your account or update an existing phone number. This must use the PUT method.
Set header Accept (optional) = the expected response format
Params
| apiKey | Required | The apiKey associates the API call with your account. |
| numberType | Required | The type of number being requested: LOCAL, TOLL_FREE or SIP. |
| number | Required | The phone number being requested. |
| smsEnabled | Required | Whether or not to enable SMS for the number: true or false (Default is false). Note: This parameter is required even if taking the default. This is only supported for LOCAL numbers. |
| smsUrl | Required | If receiving SMS to this number, this is the URL to send the SMS. SMS received without a configured URL will be sent via email. Note: This parameter is required even if not setting the URL. This is only supported for LOCAL numbers. |
| projectName | Optional | The name of the nimblevox Blast build project to be assigned to the number. Note: projectName may not be sent when groupName is sent. |
| groupName | Optional | The name of the nimblevox Blast number group in which to place the number. Note that the group must have been previously created through the Nimblevox Blast portal. When a number is assigned to a group it will automatically inherit the project assigned to the group. Note: groupName may not be sent when projectName is sent. |
Responses
| 200 | OK | |
| 201 | Created | |
| 400 | Bad Request | The message in the reply will contain more specific information regarding the nature of the error. |
| 401 | Unauthorized | API was not authorized. Check that your apiKey is correct. |
| 406 | Not Acceptable | Supported response formats are json and xml |
| 409 | Conflict | Number is already assigned to a different user |
| 500 | Internal Server Error | Error saving number changes |
Example CURL Commands
Copy the command and replace with your {apiKey} and the required and optional params.
Ordering a LOCAL number and assigning a project:
curl -X PUT -H "Accept: application/xml" "https://api.nimblevox.com/number/{number}?apiKey={apiKey}" -d "<number><numberType>LOCAL</numberType><smsEnabled>true</smsEnabled><smsUrl>http://iivip.com</smsUrl><projectName>Project X</projectName></number>"
Ordering a TOLL_FREE number and assigning it to a group.
curl -X PUT -H "Accept: application/json" "https://api.nimblevox.com/number/{number}?apiKey={apiKey}" -d "<number><numberType>TOLL_FREE</numberType><smsEnabled/><smsUrl/><groupName>Group Y</groupName></number>"
Ordering a SIP number with no project or group:
curl -X PUT -H "Accept: application/json" "https://api.nimblevox.com/number/{number}?apiKey={apiKey}" -d "<number><numberType>SIP</numberType><smsEnabled>false</smsEnabled><smsUrl/></number>"
Example XML Response
<number id='7778884444' href='api/number/7778884444'>
<numberType>TOLL_FREE</numberType>
<smsEnabled>false</>
<smsUrl/>
<projectName/>
</number>
Example JSON Response
{"number":{"id":7778884444,"href":"api/number/7778884444","numberType":"TOLL_FREE","smsEnabled":false,"smsUrl":null,"projectName":null}}
Response Field Definitions
| Element Name | Description |
| id | The requested 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. |
