====== API - Import Contacts ======

This API method allows you to send an XML-formatted list of Contacts to Sentori, which will then be imported into your database. It is intended for the bulk import of contacts; if you wish to integrate a signup process you should use the [[api-contact-signup|API  Contact Signup]] method.

[[api|Other Sentori API methods]]
===== Request =====

|Post|<nowiki>https://api.sentoriapp.com/v1/contacts.asmx/Import</nowiki>| 
|Required Headers|Content-Type: application/xml, Content-Length: <int>, ApiKey: <Guid>|
|Optional Headers|Accept-Encoding: Gzip (indicates to the API that it can compress the Response), Audience-Name: <string> (Name of the Audience created by importing the contacts), Audience-Description: <string> (Description of the Audience created by importing the contacts), Content-Encoding: Gzip (set this if your application has compressed the XML in your Request body; makes transfer of the data faster)|
|XML Structure|<code><Contacts>
  <Contact>
    <EmailAddress>user@domain.com</EmailAddress>
    <Title>Mr</Title>
    <FirstName>Joe</FirstName>
    <LastName>Bloggs</LastName>
  </Contact>
</Contacts></code>|        

===== Response =====

|Body|Empty|
|Headers|201 Created, Total-Rows: <int>, Emailable-Rows-Created: <int>, Emailable-Rows-Updated: <int>, Suppressed-Rows-Updated: <int>, Bad-Email-Address-Rows-Updated: <int>, Excluded-Duplicates: <int>, Excluded-Invalid-Emails: <int>, Excluded-Role-Based: <int>|
|Errors|400 Failed To Match Email Address Field, 400 Failed To Match All Fields, 403 Invalid API Key, 409 A Contact Import Is Already In Progress|
===== Example HTTP Transaction =====

<code>
POST https://api.sentoriapp.com/v1/contacts.asmx/Import HTTP/1.1
content-type: application/xml
apikey: e9614e92-1999-441a-89b7-707b1542c642
Content-Length: 161
audience-name: Test API Audience
audience-description: This is a test upload via the API with an audience name and description
<Contacts>
  <Contact>
  <EmailAddress>user@domain.com</EmailAddress>
  <Title>Mr</Title>
  <FirstName>Joe</FirstName >
  <LastName>Bloggs</LastName>
  </Contact>
</Contacts>
</code>

<code>
HTTP/1.1 201 Created
Total-Rows: 1
Emailable-Rows-Created: 1
Emailable-Rows-Updated: 0
Suppressed-Rows-Updated: 0
Bad-Email-Address-Rows-Updated: 0
Excluded-Duplicates: 0
Excluded-Invalid-Emails: 0
Excluded-Role-Based: 0
</code>

===== PHP Example =====

Note that this PHP example is downloadable.

<file php SentoriAPI_ImportExample.php>
<?php
/*
* PHP Sample code to access sentoriapp API
* This code will create two contacts
* 
* Date: 2013-01-10
*/
$url = 'https://api.sentoriapp.com/v1/contacts.asmx/Import';
$apikey='your sentori API key';
$xml = '<Contacts>

<Contact>
<EmailAddress>user@domain.com</EmailAddress>
<Title>Mr</Title>
<FirstName>Joe</FirstName>
<LastName>Bloggs</LastName>
</Contact>
<Contact>
<EmailAddress>user2@domain.com</EmailAddress>
<Title>Mr</Title>
<FirstName>Kis</FirstName>
<LastName>Ja</LastName>

</Contact>
</Contacts>';

$c = curl_init();

curl_setopt($c, CURLOPT_URL, $url);
curl_setopt($c, CURLOPT_RETURNTRANSFER, true);
curl_setopt($c, CURLOPT_HEADER, true);
curl_setopt($c, CURLOPT_HTTPHEADER, array('Content-Type: application/xml','apikey:'.$apikey, 'Content-length: '.strlen($xml)));

curl_setopt($c, CURLOPT_POST, true);
curl_setopt($c, CURLOPT_POSTFIELDS, $xml);
curl_setopt($c, CURLOPT_TIMEOUT, (int)30);

$xmlResponse = curl_exec($c);
curl_close ($c);
echo '<br/>Output :: <br/>'.$xmlResponse;
?> 
</file>

===== Important Notes =====

  - The "widest" Contact will dictate the Properties that exist for all Contacts in an Import. If a Contact is missing a Property, a blank value will be used for them.
  - Imported blank values will replace existing non-blank values on a Contact.