Page tree
Skip to end of metadata
Go to start of metadata

Purchase DID/DDI number.

Sample URIs


List of parameters:

outputYesOne of :  json , xml , csv
usernameYesYour account username or API username.
passwordYesYour account password or API password.
numberYesThe phone number you wish to purchase - get this from the output of GetDIDs function.
descriptionNoDescription of this phone number (intended usage or end-customer name, etc)
typeNoCall forward destination (scroll down for more info) . Values 1 or 2 should suffice for most users.
ringtypeNo1 - sequential (try uri, uri2,uri3 in order ; 2 - random (try uri, uri2, uri3 randomly) ; 3 - simultaneous (try all uris at the same time)
ringstyleNo1 - just ring ; 2 - replace ring with music on hold
uriNoSIP URI : valid number@domain for "type" => 1 or valid phone number in E164 format for "type" => 2 (no +, no 00, no 011 prefixes)
uri2NoSIP URI : valid number@domain for "type" => 1 or valid phone number in E164 format for "type" => 2 (no +, no 00, no 011 prefixes)
uri3NoSIP URI : valid number@domain for "type" => 1 or valid phone number in E164 format for "type" => 2 (no +, no 00, no 011 prefixes)

Valid http or https URL - we will send a POST request containing a JSON string
Sample :

{"event": ?, "status": ?, "timestamp": ?, "caller": ?, "called": ?, "callid": ?}
smsringtypeNo1 - E-Mail , 2 - URL ; 3 - SMS Flow ; 4 - Autoreply ; 5 - SIP ; 6 - XMPP ; 7 - RSVP ; 8 - SIP Account ; 9 - Hosted PBX; 11 - MailChimp
smsuriNoValid URI (email address if smsringtype is 1 , valid URL if smsringtype is 2 , valid identifiers for the other options)
faxdetectNo(retired) - If set to 1 , call will be picked up and system will listen for fax tones for up to {faxring} seconds
faxemailNo(retired) - E-Mail address to forward fax message to
faxringNo(retired) - How many seconds should we listen for ring tones?
vmNo(retired) - Should the call be picked up by the VoiceMail system if no answer?
vmringNo(retired) - How many seconds should we ring before forwarding call to VoiceMail?
vms2tNo(retired) - Voicemail Speech 2 Text (convert voicemail messages to text)
vmemailNo(retired) - Send Voicemail as e-mail to this e-mail address
cnamNoSet to 1 to enable CNAM queries (cost of $0.004 applies per CNAM query) ; set to 0 to disable; Defaults to 0
recordNoSet to 1 to record inbound calls ; Set to 0 to disable; Defaults to 0
screeningNo(retired) Enable Call Screening; Each call is picked up by the system which asks the caller to identify themselves. Defaults to 0
channelsNoHow many channels are we purchasing? Defaults to 2 (or in some cases 1, depending what is the number of free channels on that number)
atcdNo(retired) Anti telemarketer call detection : System picks up the calls and listens for automated messages before deciding if call will be further forwarded to you
autorenewNoPossible values: 1: Renew the number automatically ; 2: Do not renew the number (number expires at the end of month). Default value: 1
overflowNoIf your number receives more simultaneous calls than the allocated number of channels, automatically allow the extra calls (a cost per minute applies)

2Dial (dial out via PSTN)
3(deprecated) Call Flow (to be removed)
4(deprecated) Audio Recording (to be removed)
7SIP Account
9DTMF Test
11(deprecated) Call Queue (to be removed)
13(deprecated) Calling Card (to be removed)
15Hosted PBX

Please note that for all the parameters that are deprecated or retired , you can still achieve the same functionality by using our Hosted PBX product.
Reason for retiring these features is because our Hosted PBX product incorporates all the features we moved away from the number and then some more other cool features.

Information on output values:

Key NameDescription
RETURNPhone number that we have purchased or an error code if purchase failed
STATUSError or success code
DESCRIPTIONError code description

Status codes description:

Status codeInfoDescription
200All went well, this was a successful purchaseSuccess
-1325Number has been reserved by another userNumber has been temporarily reserved
-1320Number has been reserved by yourselfPlease call the unreserve function before purchasing this number
404Number not found or just releasedNumber not found or it was just released - in which case please allow up to half hour for it to return to inventory
100Incorrect username or passwordAuthentication failed
99Not enough balance to complete the purchaseNot enough balance to complete the purchase
-1265Documents are required for this purchaseList of required documents should be returned as HTML
403Number not available for purchaseNumber unavailable for purchase
88Cannot allocate required number of channelsNot enough channels available for this specific number
500Internal server error (let us know about it)Internal server error (let us know about it)
505Not implemented (let us know about it)Not implemented (let us know about it)
888Exception (let us know about it)Exception (let us know about it)
-220Number has been reserved by adminNumber has been reserved by admin
-165Number has already been soldNumber has already been sold (check your account, maybe you're the lucky owner?)
-275Number has been removed from inventoryNumber has been removed from inventory
-1210Number has not been cleared yet (inactive)Number has not been cleared yet (inactive)


If you like to keep things simple, its just a matter of defining a default ringto URI ( , in the "URI Settings" tab).

  1. Click on Profile Settings

  2. Click on "URI Settings" , fill in the required values and save:

  3. Call the Purchase API URL:


Sample successful output - JSON


Sample unsuccessful output - JSON

{"DATA":[{"RETURN":-165,"STATUS":-165,"DESCRIPTION":"Number has already been sold"}]}

Sample unsuccessful output - XML

<?xml version="1.0"?>
  <DESCRIPTION>Number has already been sold</DESCRIPTION>