purchaseVoxNumbers¶

Request Method: POST

Description: Purchase one or more VoxNumbers from an XML request. This feature includes a call-back method to send results to a specified URL for any requests that are not fulfilled immediately.

URL: https://api.iovox.com:444/Purchase?v=3&method=purchaseVoxNumbers

The following parameters can be sent in the querystring:

Parameter	Description	Default Value	Data Type	Mandatory
v	API version to use		INTEGER	YES

Payload¶

The following XML payload must be sent with a purchaseVoxNumbers request:

<?xml version="1.0" encoding="utf-8"?>
<request>
    <callback_url>http://my.company.com/orderCallback.php</callback_url>
    <cc_list>mail@mail.com</cc_list>
    <dynamic_quantity>TRUE</dynamic_quantity>
    <items>
        <item>
           <country_code>44</country_code>
           <area_code>151</area_code>
           <number_type>GEOGRAPHIC</number_type>
           <quantity>2</quantity>
           <additional_information>
                <firstname>Bastien</firstname>
                <lastname>Kerigan</lastname>
                <company>Iovox</company>
                <street>a street</street>
                <building_number>21</building_number>
                <city>Saint Nazaire</city>
                <zipcode>44600</zipcode>
           </additional_information>
        </item>
        <item>
        .....
        </item>
    </items>
 </request>

Payload Description¶

Node Name	Description	Default Value	Data Type	Mandatory
callback_url	Url of your callback script in the following format (max 120 characters long): http://example.com or (advanced example) https://user:pass@example.com/path/page?param=value		STRING	NO
cc_list	A list of emails separated by commas		STRING	NO
dynamic_quantity	If the dynamic_quantity is set to TRUE then only the number of available VoxNumbers in stock will be purchased, and the order quantity will be amended to reflect the number of available VoxNumbers.	FALSE	STRING	NO
country_code	The IDD (International Direct Dialing) of the country		INTEGER	YES
area_code	The Area Code specific for the region we want to purchase		INTEGER	YES (unless post code)
post_code	The Post Code specific for the region we want to purchase (UK and FR Only)		STRING	NO
city_name	The name of the city. The number you buy can be specific to a city (optional), the name need to be the same as the one returned by getVoxnumberRegions		STRING	NO
number_type	The Type of number we want to purchase. We can provide three type of numbers: NATIONAL, GEOGRAPHIC, TOLLFREE		STRING	YES
quantity	The amount of numbers we want to buy		INTEGER	YES
additional_information	Some countries need additional legal information to purchase a VoxNumber. You can use the API method "getVoxnumberRegions" to know if it is required for your country. The provided address has to be in the corresponding country. At 16th July 2011 this includes Croatia, France, Germany, Ireland, Netherlands, Norway and Singapore, but is potentially subject to change		XML	NO (depending on country)
additional_information > firstname	First name of the billing contact.		STRING	YES IF ADDRESS REQUIRED
additional_information > lastname	Last name of the billing contact.		STRING	YES IF ADDRESS REQUIRED
additional_information > company	Company name of the billing contact.		STRING	YES IF ADDRESS REQUIRED
additional_information > street	Street name of the billing contact.		STRING	YES IF ADDRESS REQUIRED
additional_information > building_number	Building number of the billing contact.		INTEGER	YES IF ADDRESS REQUIRED
additional_information > city	City of the billing contact.		STRING	YES IF ADDRESS REQUIRED
additional_information > zipcode	Zipcode of the city for the billing contact.		STRING	YES IF ADDRESS REQUIRED

Result¶

Error Result

HTTP Code	Error String	Resolution
400	API Version Empty	Add a value for the v parameter in the query string
400	API Version Invalid	Correct v parameter
400	Request Method must be POST. x attempted	Switch request method x to POST
400	Page Number not an integer	Remove non-numerics from page
400	XML Empty	Add xml to the request body
400	XML parse error. x at line y, column z	Correct XML at point x on line y, column z
400	Request Empty	Add at least one item to the request
400	Dynamic Quantity x of y Invalid	Change the Dynamic Quantity to TRUE or FALSE
400	Country Code x of x Empty	Add country_code for Item x of y (total)
400	Area Code x of x Empty	Add area_code for Item x of y (total)
400	Number Type x of x Empty	Add number_type for Item x of y (total)
400	Quantity x of x not an integer	Remove non-numerics from quantity
400	Quantity must be between 1 and 250	Correct the Quantity parameter
400	The requested Number Type x of x is not valid. The valid values are NATIONAL, GEOGRAPHIC, TOLLFREE	Change number_type for Item x of y (total) to NATIONAL, GEOGRAPHIC or TOLLFREE
400	firstname x of y Empty	Add firstname parameter in Item x of y
400	lastname x of y Empty	Add lastname parameter in Item x of y
400	Company Name x of y Empty	Add company parameter in Item x of y
400	street x of y Empty	Add street parameter in Item x of y
400	building_number x of y Empty	Add building_number parameter in Item x of y
400	building_number x of y not an integer	Correct building_number parameter in Item x of y
400	city x of y Empty	Add city parameter to Item x of y
400	zipcode x of y Empty	Add zipcode parameter to Item x of y
400	Basket Item x of y is not correct.	The phone number requested in the item x of y does not exist. Choose an existing one by requesting the method getVoxnumberRegions first, it provide a matching country_code, area_code and number_type.
500	Internal Server Error	Retry later

Success Result :¶

If the order is pending:

<?xml version="1.0" encoding="utf-8"?>
<response>
    <order_reference>a0d7c5264b34fd6ea36e75a4363adss9</order_reference>
     <order_status>PENDING</order_status>
     <voxnumbers></voxnumbers>
 </response>

Please note that an order is PENDING if at least one VoxNumber could not be fulfilled.

If is set to true then only the available numbers will be returned in the node. The will be FULFILLED as this order is considered as complete.

If order has been completed :

<?xml version="1.0" encoding="utf-8"?>
<response>
    <order_reference>a0d7c5264b34fd6ea36e75a4363adss9</order_reference>
     <order_status>FULFILLED</order_status>
     <voxnumbers>
        <voxnumber>
            <country_code>44</country_code>
            <area_code>151</area_code>
            <full_voxnumber>441512100200</full_voxnumber>
        </voxnumber>
        <voxnumber>
            <country_code>44</country_code>
            <area_code>151</area_code>
            <full_voxnumber>441513100200</full_voxnumber>
        </voxnumber>
        <voxnumber>
             ...
        </voxnumber>
     </voxnumbers>
 </response>

¶

Description

Node Name	Description	Data Type
order_reference	A reference for your order	STRING
order_status	PENDING : Order is not completed,you will receive other VoxNumbers in your account. FULFILLED : Your order is completed, all VoxNumbers are now in your account.	STRING
voxnumber	Description of VoxNumbers that have been fulfilled. If some numbers have been ordered but are not available, these are not displayed in that XML, and will be added to your account once fulfilled
voxnumber>area_code	The Voxnumber Area Code for the country region	INTEGER
voxnumber>country_code	The Voxnumber Country IDD	INTEGER
voxnumber>full_voxnumber	The Voxnumber	INTEGER

Callback¶

You can receive a report when you order is updated, then when a fulfilled VoxNumber order is added to your account. A raw XML is posted to the callback_url via HTTP POST. The call-back URL can be set in the purchaseVoxNumbers request. Requests are sent until all VoxNumbers order are fulfilled.

The following XML payload is sent to you callback url:

<?xml version="1.0" encoding="utf-8"?>
<order>
     <order_reference>a0d7c5264b34fd6ea36e75a4363adss9</order_reference>
     <order_status>FULFILLED</order_status>
     <voxnumbers>
        <voxnumber>
             <country_code>44</country_code>
             <area_code>151</area_code>
             <full_voxnumber>441512100200</full_voxnumber>
        </voxnumber>
        <voxnumber>
            ...
        </voxnumber>
     <voxnumbers>
 </order>

Please note that a callback could contain PENDING VoxNumbers.

In that case the will still be PENDING and only some of the VoxNumbers will be included in the response, another callback will be sent once the order is FULFILLED.

Callback XML Description¶

Node Name	Description	Data Type
order_reference	A reference for your order	STRING
order_status	PENDING : Order is not completed,you will receive other VoxNumbers in your account, then receive others callbacks. FULFILLED : Your order is completed, all VoxNumbers are now in your account.	STRING
voxnumber	Description of VoxNumbers that have been fulfilled. If some numbers have been ordered but are not available, these are not displayed in that XML, and will be added to your account once fulfilled
voxnumber>area_code	The Voxnumber Area Code for the country region	INTEGER
voxnumber>country_code	The Voxnumber Country IDD	INTEGER
voxnumber>full_voxnumber	The Voxnumber	INTEGER