Add contacts to address book

The AddContactsToAddressBook method is now considered obsolete and you should use AddContactsToAddressBookWithProgress where possible.

This method adds multiple contacts stored in a CSV or XLS file to an address book using a single API call. It allows you to set the information about the contacts you are uploading and the address book you are uploading them to.

We recommend that you use a .CSV file wherever possible. It is useful when you need to upload multiple contacts in one go into the dotMailer system. As each call only counts as one API call it allows you to easily stay below your API limit whilst uploading multiple contacts. It has the benefit of being run through our data watchdog so you know the data you are importing is of a good quality.

Guidance Notes

This method will create the contact being added if it doesn't already exist which means you do not need to call a method such as CreateContact before calling it. You may upload either a .csv or .xls file. It must contain one column with the heading "Email" or the translated equivalent if your account is using a language other than English. Other columns will attempt to map to your custom data fields. There is a 10MB upload limit per file.

As the import goes through our data watchdog there might be a delay between uploading the contacts and them being successfully added to the address book.

Parameters

username	string	This is the username from your API key. It is in the format of an email address and will look similar to apiuser-908709770324@apiconnector.com	required
password	string	This is the password from your API key.	required
addressBookId	int	This is the Id of the address book which you would like to upload the contact to.	required
data	base64Binary	This is the original file, encoded in Base64 format.	required
dataType	CSV or XLS	This is the type of file which you are uploading, either .CSV, or .XLS. At this time, XLSX is not supported.	required

Return values

None.

Error responses

ERROR_ADDRESSBOOK_NOT_FOUND
ERROR_ADDRESSBOOK_NOTWRITABLE
ERROR_APIUSAGE_EXCEEDED
ERROR_CONTACT_INVALID
ERROR_CONTACT_SUPPRESSED
ERROR_CONTACT_TOOMANY
ERROR_DATAFIELD_NOTFOUND
ERROR_IMPORT_TOOMANYACTIVEIMPORTS
ERROR_INVALID_LOGIN
ERROR_NO_EMAIL_COLUMN
ERROR_PARAMETER_INVALID
ERROR_SYSTEM_SERVICETEMPORARILYUNAVAILABLE
ERROR_UNKNOWN

Request

POST /API.asmx HTTP/1.1
Host: apiconnector.com
Content-Type: text/xml; charset=utf-8
Content-Length: length
SOAPAction: "http://apiconnector.com/AddContactsToAddressBook"

Example of use in C# .NET

/// <summary>
/// This method adds multiple contacts stored in a CSV or XLS file to an address book
/// using a single API call. It allows you to set the information about the contacts
/// you are uploading and the address book you are uploading them to
/// </summary>
public void AddContactsToAddressBook()
{
const string username = "apiuser-XXXXXXXXXXXX@apiconnector.com";
const string password = "password";
const int addressBookId = 1;  // ID of the target address book
const string sourceFileName = @"C:\work\git\DotDigital\API\APISamples\testdata\Contact Demo Data - 3k.xls";
const int readSize = 10 * 1024;       // aim to read in 10Kb at a time from the source file
Console.WriteLine("AddContactsToAddressBook");
Console.WriteLine("------------------------");
// Get an instance to the web reference
com.apiconnector.API api = new com.apiconnector.API();
// Read the source file into memory
try
{
byte[] buffer;
// first step is to read the source file into memory
using (BinaryReader br = new BinaryReader(File.Open(sourceFileName, FileMode.Open, FileAccess.Read)))
{
// how much data are we going to read
long totalLength = br.BaseStream.Length;
long read = 0;
// we need somewhere to put our file data
buffer = new byte[totalLength];
while (read != totalLength)
{
byte[] temp = br.ReadBytes(readSize);
int amountRead = temp.Length;
// copy over the amount of data we have read into our
// main buffer
for (int i = 0; i < amountRead; i++)
{
buffer[read + i] = temp[i];
}
// update the amount of data we have read
read += amountRead;
}
// close the stream - we are done with it.
br.Close();
}
api.AddContactsToAddressBook(username, password, addressBookId, buffer, com.apiconnector.ImportDataType.XLS);
// if we are still here - we are all done
Console.WriteLine("Imported data from file [{0}]", sourceFileName);
}
catch (SoapException ex)  // catch any soap issues/errors from the web service
{
Console.WriteLine("Error -> {0}", ex.Message);
}
Console.WriteLine();
}

Example of use in PHP

<?php
$username = "APIUsernameHere"; //Your API username
$password = "***********";  //your API password
$client = new SoapClient("http://apiconnector.com/api.asmx?WSDL"); //Instantiate the Soap client
//We will upload the Contactslist.csv  file to the system.
$file =  'Contactslist.csv' ;
$handler = fopen($file,'r') ;
$readfile = fread($handler,filesize($file));
$encoded = base64_encode($readfile);
$typedVar = new SoapVar($encoded,XSD_BASE64BINARY,"string","http://www.w3.org/2001/XMLSchema"); //Declare the type as BASE64Binary    string
$addressbookid=469226;
$datatype = "CSV";
$params = array("username"=>$username,
"password"=>$password,
"addressbookID"=>$addressbookid,
"data"=>$typedVar,
"dataType"=>$datatype ) ;
return $client->AddContactsToAddressbook($params);
?>

Sample request

POST /API.asmx HTTP/1.1
Host: apiconnector.com
Content-Type: text/xml; charset=utf-8
Content-Length: length
SOAPAction: "http://apiconnector.com/AddContactsToAddressBook"
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<AddContactsToAddressBook xmlns="http://apiconnector.com">
<username>string</username>
<password>string</password>
<addressbookID>int</addressbookID>
<data>base64Binary</data>
<dataType>CSV or XLS</dataType>
</AddContactsToAddressBook>
</soap:Body>
</soap:Envelope>

Sample response

HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: length
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<AddContactsToAddressBookResponse xmlns="http://apiconnector.com" />
</soap:Body>
</soap:Envelope>

About the API

Address books

Contacts

Campaigns

Reporting

SMS

Account

Images

Documents

Templates