Request Method: POST
Description: Create a new Node complete with Links, Category data, Rule Template, Contact details and assign a voxnumber.
URL: https://api.iovox.com:444/Nodes?v=3&method=createNodeFull
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 an createNodes request:
<?xml version="1.0" encoding="utf-8"?>
<request>
<node>
<node_id>ABC123</node_id>
<node_name>Tom Business</node_name>
<node_type>Business</node_type>
<node_date>2008-11-19 14:10:46</node_date>
<links>
<link>
<link_id>ABC123</link_id>
<link_name>Media News</link_name>
<link_type>Newspaper</link_type>
<link_date>2008-11-19 15:15:45</link_date>
<click_to_call>1</click_to_call>
<!-- for more information how to get the rules_variables go to getVariableRulesOfTemplate API method -->
<rules_variable>
<rule>
<rule_id>call</rule_id>
<rule_type>call</rule_type>
<rule_label>Call</rule_label>
<contact>
<contact_id>23113123</contact_id>
<business_phone>449789122233</business_phone>
<!-- any other fields from createContacts API method -->
</contact>
<caller_message>
<sound_files>
<sound_file>sound group 1|whisper called</sound_file>
</sound_files>
</caller_message>
<called_message>
<sound_files>
<sound_file>sound group 1|whisper caller</sound_file>
<sound_file>sound group 2|Whisper to the Business</sound_file>
</sound_files>
</called_message>
</rule>
</rules_variable>
<rule_template_name>Call Sales</rule_template_name>
<assign_voxnumber>
<method>BY AREA</method>
<voxnumber_idd>44</voxnumber_idd>
<area_code>20</area_code>
</assign_voxnumber>
<categories>
<category>
<parent_category_id>1</parent_category_id>
<category_id>10</category_id>
<value>London</value>
</category>
<category>
....
</category>
</categories>
</link>
</links>
</node>
</request>
Payload Description¶
| Field Name | Description | Default Value | Data Type | Mandatory |
|---|---|---|---|---|
| node_id | ID to identify the Node by in future API requests. Keyword AUTOINCREMENT() can be used here to set this to 1 greater than the total number of Nodes in account. If using a Node ID that already exists, the specified Links will be attached to the existing Node | STRING | YES | |
| node_name | Name of the Node | STRING | YES | |
| node_type | The type of Node | STRING | YES | |
| node_date | A reference date to be stored alongside the Node. Node date format is YYYY-MM-DD HH:MM:SS with hours, minutes and seconds being optional. Hours, minutes and seconds defaults to 00:00:00 | CURRENT DATE/TIME | DATETIME | NO |
| node>links>link>link_id | ID to identify the Link by in future API requests. Keyword AUTOINCREMENT() can be used here to set this to 1 greater than the total number of Links in account | STRING | YES | |
| node>links>link>link_name | Name of the Link | STRING | YES | |
| node>links>link>link_type | The type of Link | STRING | YES | |
| node>links>link>link_date | A reference date to be stored alongside the Node. Node date format is YYYY-MM-DD HH:MM:SS with hours, minutes and seconds being optional. Hours, minutes and seconds defaults to 00:00:00 | CURRENT DATE/TIME | DATETIME | NO |
| node>links>link>click_to_call | Click to Call status - 1 (on) or 0 (off) | 1 | INTEGER | NO |
| node>links>link>rule_template_name | The Name of the template we want to assign to the Link. | STRING | NO | |
| node>links>link>categories>category>parent_category_id | The ID of the Parent Category to attach to. For example, adding London to the parent Category for UK. This is only required if the Category ID does not exist. If you want to create a subcategory you will need to add a parent_category_id which exist already and a not empty value. If you do not want to create a new Category, label is not required | STRING | NO, unless Category ID does not exist | |
| node>links>link>categories>category>category_id | Category ID of the category we want to add to the Link. | STRING | YES | |
| node>links>link>categories>category>value | The Value of the category we want to apply. | STRING | NO, unless Category ID does not exist | |
| node>links>link>assign_voxnumber>method | The method we want to use for assign a VoxNumber. Possible Values: "BY AREA", "BY VOXNUMBER", "BY POSTCODE" | STRING | NO | |
| node>links>link>assign_voxnumber>voxnumber_idd | The IDD of the VoxNumber we want to apply. E.G: 44 | STRING | YES for assign By AREA | |
| node>links>link>assign_voxnumber>area_code | The area code of the voxnumber we want to apply. E.G: 020 for LONDON | STRING | YES for assign By AREA | |
| node>links>link>assign_voxnumber>fallback_city | If not sufficient number in the area_code, will attach numbers in other area codes from the same city. Only available if method is "BY AREA" | FALSE | BOLEAN | NO |
| node>links>link>assign_voxnumber>fallback_region | If not sufficient number in the area_code, will attach numbers in other area codes from the same city. Only available if method is "BY AREA" and in Canada and United States | FALSE | BOLEAN | NO |
| node>links>link>assign_voxnumber>fallback_country | If not sufficient number in the area_code, will attach numbers in other area codes from the same country. Only available if method is "BY AREA" | FALSE | BOLEAN | NO |
| node>links>link>assign_voxnumber>full_voxnumber | The VoxNumber we want to apply. E.G: 442071002003 | INTEGER (e164 format) | YES for assign By VoxNumber | |
| node>links>link>assign_voxnumber>voxnumber_country | The VoxNumber's associated country name. List of supported countries for Postcode search | STRING | YES for assign By Postcode | |
| node>links>link>assign_voxnumber>postcode | The full postcode you are searching for. Postcodes will be grouped by out-code (i.e. the first half of the postcode) to match available stock. For example, if you require a VoxNumber in W11 3EP for Link 1 and a VoxNumber in W11 4FQ for Link 2 and have only 1 VoxNumber in your account in London (020) both of these will fall back to the same closest matching area code if a fallback_area_distance is specified as they are both in the outcode W11 | STRING | YES for assign By Postcode | |
| node>links>link>assign_voxnumber>fallback_area_distance | If there is no VoxNumber available for the exact postcode, the fallback distance will return the closest within the range. E.g. If the fallback_area_distance is set to 20, the VoxNumber attached can be 15Kms away from the postcode, but not 25Kms. | 0 | NUMBER (in Kilometers) | NO |
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 | 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 node to the request |
| 400 | Node ID x of y Empty | Add node_id for Node x (item) of y (total) |
| 400 | Node Name x of y Empty | Add node_name for Node x (item) of y (total) |
| 400 | Node Type x of y Empty | Add node_type for Node x (item) of y (total) |
| 400 | Node Date x of y Invalid | Correct node_date for Node x (item) of y (total) |
| 400 | Duplicate Node ID Received | Change node_id to be unique |
| 400 | Link ID x of y Empty | Add link_id for Link x (item) of y (total) |
| 400 | Link ID x of y already exists | Correct the link_id for Link x (item) of y (total) |
| 400 | Link Name x of y Empty | Add link_name for link x (item) of y (total) |
| 400 | Link Type x of y Empty | Add link_type for link x (item) of y (total) |
| 400 | Link Date x of y Invalid | Correct link_date for link x (item) of y (total) |
| 400 | Click to Call Status x of y Invalid | Correct click_to_call status for link x (item) of y (total) |
| 400 | All validation messages from createContacts | See createContacts error messages list |
| 400 | Rule Template Name x of y does not exist: z | Correct rule_template_name for link x (item) of y (total) as z does not exist |
| 400 | Duplicate Link Name x for Node y in the XML | Correct link name so that it is unique within the links attached to Node y |
| 400 | Method x of y Empty | Add method x (item) of y (total) to the request |
| 400 | Method x of y Invalid | Correct method x (item) of y (total) to be "BY AREA", "BY VOXNUMBER" or "BY POSTCODE" |
| 400 | VoxNumber IDD x of y Empty | Add voxnumber_idd x (item) of y (total) |
| 400 | VoxNumber IDD x of y Invalid | Correct voxnumber_idd x (item) of y (total) |
| 400 | Voxnumber x of y Empty | Add an existing voxnumber to request x (item) of y (total) or change method |
| 400 | Voxnumber x of y is not an Integer | Correct the full voxnumber to request x (item) of y (total) or change method |
| 400 | Duplicate Voxnumber Received | Correct the duplicated full voxnumber in the XML |
| 400 | Area Code x of y Empty | Add a correct area code to request x (item) of y (total) or change method |
| 400 | Area Code x of y not an integer | Correct the area code request x (item) of y (total) or change method |
| 400 | Fallback City x of y Invalid | Correct the fallback city to be TRUE, FALSE. |
| 400 | Fallback Region x of y Invalid | Correct the fallback region to be TRUE, FALSE. |
| 400 | Fallback Country 1 of 1 Invalid | Correct the fallback country to be TRUE, FALSE. |
| 400 | Insufficient VoxNumbers available in Area Code x and Voxnumber IDD y | Buy more VoxNumbers in city x for Voxnumber IDD y or remove some requests until the required amount falls beneath the total VoxNumbers available in your account. Bare in mind that it counts the UNASSIGNED full_voxnumbers in your account |
| 400 | Category Id x of y Empty | Add the Category ID for the Category x (item) of y (total) |
| 400 | Parent ID x of y Empty | Add the Parent ID for the Category x (item) of y (total) |
| 400 | Parent ID x of y does not exist | Correct the Parent ID for the Category x (item) of y (total) |
| 400 | Value x of y Empty | Add the Value for the Category x (item) of y (total) |
| 400 | Multiple matches for Sound Label (x) Sound Group: (y,z) | Specify the sound group (y,z) for this sound label (x) |
| 400 | There is no VoxNumber available in your account for this Postcode or the fallback area | Extra numbers need to be purchased in this area |
| 400 | The country x is not supported for Postcode search | Choose a supported country of use an other "method" |
| 400 | Postcode x does not exist in country id y | Change the postcode for an existing one |
| 500 | Internal Server Error | Retry later |
Success Result¶
Includes Node/Link IDs generated by any AUTOINCREMENT() and any VoxNumbers attached to the Links