createContacts¶
Request Method: POST
Description: Creates a new contact using a sub set of fields, as opposed to V-CARD format
URL: https://api.iovox.com:444/Contacts?v=3&method=createContacts
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 createContacts request:
<?xml version="1.0" encoding="utf-8"?>
<request>
<contact>
<contact_id>client123</contact_id>
<display_name>John Smith</display_name>
<first_name>John</first_name>
<last_name>Smith</last_name>
<email>jsmith@iovox.com</email>
<email_2>jsmith@iovox.com</email_2>
<company>IOVOX</company>
<mobile_phone>449789123123</mobile_phone>
<home_phone>441223432123</home_phone>
<business_phone>441223432987</business_phone>
<business_fax>441223432984</business_fax>
<work_address_1>155 Abbey Street</work_address_1>
<work_address_2>Westminister</work_address_2>
<work_city>London</work_city>
<work_country>United Kingdom</work_country>
<work_postcode>W1 5P6</work_postcode>
<home_address_1>155 Abbey Street</home_address_1>
<home_address_2>Westminister</home_address_2>
<home_city>London</home_city>
<home_country>United Kingdom</home_country>
<home_postcode>W1 5P6</home_postcode>
<notes>This is a note.</notes>
</contact>
<contact>
...
</contact>
</request>
Payload Description¶
Node Name | Description | Default Value | Data Type | Mandatory |
contact > contact_id | A unique ID to reference the contact by | STRING | YES | |
contact > display_name | The full name of the contact. This must be unique when in combination with any of this contact's phone numbers | first_name last_name or company | STRING | NO |
contact > first_name | The first name of the contact | STRING | NO | |
contact > last_name | The last name of the contact | STRING | NO | |
contact > email | The email address for the contact | STRING | NO | |
contact > email_2 | An additional email address for the contact | STRING | NO | |
contact > company | The name of the company to which the contact belongs | STRING | NO | |
contact > mobile_phone | The internationalised mobile phone number for the contact | STRING | NO | |
contact > home_phone | The internationalised home phone number for the contact | STRING | NO | |
contact > business_phone | The internationalised business phone number for the contact | STRING | NO | |
contact > business_fax | The internationalised business fax number for the contact | STRING | NO | |
contact > home_country | A string representing the country in which the contact resides. While this is not mandatory if it is absent and home_phone is provided in the payload a 'best guess' at the contact's country will be made based on the phone number provided. This will be stored against the contact's details | STRING | NO | |
contact > business_country | A string representing the country of the contact's business. While this is not mandatory if it is absent and business_phone is provided in the payload a 'best guess' at the contact's business country will be made based on the phone number provided. This will be stored against the contact's details | STRING | NO | |
contact > notes | Any notes associated with the contact | STRING | 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 contact to the request | ||
400 | Contact ID x of y Empty | Add contact_id to contact x (item) of y (total) | ||
400 | Contact ID x of y already exists | Removed or change contact_id x (item) of y (total) | ||
400 | Duplicate Contact ID Received | Change contact_id to be unique | ||
400 | First Name x of y Invalid | Correct first name with only alphabetic characteres | ||
400 | Last Name x of y Invalid | Correct last name with only alphabetic characteres | ||
400 | Home Phone x of y is not internationalised | Correct home_phone x (item) of y (total) so it is in an internationalised format | ||
400 | Contact x of y must have either First name, Last name or Company name | Add first and last name and/or Company name in the contact x (item) of y (total) | ||
400 | Business Phone x of y is not internationalised | Correct business_phone x (item) of y (total) so it is in an internationalised format | ||
400 | Mobile Phone x of y is not internationalised | Correct mobile_phone x (item) of y (total) so it is in an internationalised format | ||
400 | Business Fax x of y is not internationalised | Correct business_fax x (item) of y (total) so it is in an internationalised format | ||
400 | Display Name and Phone Number Combination x of y already exists | Change the display_name and one or more phone numbers in Contact x (item) of y (total) to a combination that doesn't already exist, or use the updateContacts function to update the related contact | ||
400 | Display Name and Phone Number Combination duplicated | Remove any duplicate display_name and phone number combinations from the XML | ||
400 | Home Country x of y Invalid | Correct home_country x (item) of y (total) so that is matches a country name returned by Countries::getCountries | ||
400 | Business Country x of y Invalid | Correct business_country x (item) of y (total) so that is matches a country name returned by Countries::getCountries | ||
500 | Internal Server Error | Retry later |