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

Success Result¶

HTTP/1.1 201 Created