Maximize productivity with personalized, automated calling

Voice Self-Service for your growing business needs

Order Number

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

  • application/xml (default)
  • application/json


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.


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" "{number}?apiKey={apiKey}" -d "<number><numberType>LOCAL</numberType><smsEnabled>true</smsEnabled><smsUrl></smsUrl><projectName>Project X</projectName></number>"

Ordering a TOLL_FREE number and assigning it to a group.

curl -X PUT -H "Accept: application/json" "{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" "{number}?apiKey={apiKey}" -d "<number><numberType>SIP</numberType><smsEnabled>false</smsEnabled><smsUrl/></number>"

Example XML Response

   <number id='7778884444' href='api/number/7778884444'>

Example JSON Response


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.