Contacts Import | Knowledge Base

Overview

You can use this request to create many contacts at once. This request is similar to the Create Contacts in Bulk method, but it runs the contact creation asynchronously.

Once you make the request, we will store the data you have sent and immediately give you a response saying that the data is stored. Then the data will be processed on our side without you having to wait for it to be done within the scope of the API request. Because of this, it should allow for a lot more contacts to be sent at once, whereas bulk create is limited to 2,000 at a time.

The Method

Type	Request	Method
REST	POST	https://[Your URL]/api/2.0/contacts/import
XML-RPC	Call	contacts.ListContacts

Your URL is the address of your install.

Your method must be structured as follows:

ImportContacts(array $contacts) : array

Parameters

Required Parameters

The $contacts function must be passed as an array of contacts.

As with creating single contacts, you must create a new contact with either an email address or a mobile phone number. You must also specify the lists the contact will belong to, and their subscription status.

Property	Type	Description	Default	Required	Read Only
list_id	array	An array of list IDs with the subscription status for the contact. For example: array(1 => ‘unconfirmed’, 2 => ‘subscribed’) will subscribe the contact to list with ID 2, and add the contact as an unconfirmed contact to list 1.	empty	yes	no
email	string	Email	empty	no	no
mobile	string	Mobile	empty	no	no

Optional Parameters

You may include any of these optional parameters when adding a contact:

Property	Type	Description	Default	Required	Read Only
country_id	integer	Country identifier	1	no	no
city_id	integer	City identifier	1	no	no
name	string	First Name	empty	no	no
last name	string	Last Name	empty	no	no
status	string	Status Possible values: on / off / suppressed	on	no	no
preferred_email_format	string	Email format Possible values: html / text	HTML	no	no
title	string	Title	empty	no	no
company_position	string	Position	empty	no	no
company_name	string	Company Name	empty	no	no
department	string	Department	empty	no	no
industry	string	Industry	empty	no	no
address	string	Address	empty	no	no
city	string	City	empty	no	no
country	string	Country	empty	no	no
state	string	Province / State	empty	no	no
zip	string	Postal / ZIP code	empty	no	no
telephone_office	string	Work Number	empty	no	no
telephone_home	string	Home Number	empty	no	no
telephone_fax	string	Fax Number	empty	no	no
date_of_birth	integer	Date of birth (deprecated)	empty	no	no
tags	string	JSON array containing tag names	empty	no	no
birth_date	string	Date of birth	empty	no	no
gender	string	Gender Possible variables: unknown / male / female	empty	no	no
marital_status	string	Marital status Possible values: unknown / single / married	empty	no	no
education_level	string	Education level	empty	no	no
hash	string	hash_key	empty	no	no
unique_id	string	Unique import identifier	empty	no	no
id	integer	ID	empty	no	yes
date_create	integer	Date created	empty	no	yes
score	float	Contact score	2	no	yes
rating	integer	Contact rating score	2	no	yes
email_status	string	Email status Possible values: none / bouncing / bounced / always send	none	no	yes
create_notifications	string	Create notification Possible values: yes / no	no	no	no
email_bounce_hard_count	integer	Hard email bounces	0	no	yes
email_bounce_soft_count	integer	Soft email bounces	0	no	yes
block_bounce_count	integer	Consecutive block bounces	0	no	yes
sms_bounce_hard_count	integer	Hard SMS bounces	0	no	yes
sms_bounce_soft_count	integer	Soft SMS bounces	0	no	yes
sms_bounce_consecutive_count	integer	Consecutive SMS bounces	0	no	yes
complaints_count	integer	Complaints	0	no	yes
forward_count	integer	Forwards	empty	no	yes
invite_count	integer	Invites	empty	no	yes
bounce_unidentified_count	integer	Unidentified bounces	0	no	yes
autoresponder_count	integer	Autoresponders	0	no	yes
email_message_ids	string	Email message identifiers	empty	no	yes
sms_message_ids	string	SMS message identifiers	empty	no	yes
email_message_count	integer	Email Messages	0	no	yes
sms_message_count	integer	SMS Messages	0	no	yes
message_reads_inferred	integer	Inferred reads	0	no	yes
message_reads_unique	integer	Unique reads	0	no	yes
message_link_clicks	integer	Link clicks	0	no	yes
message_link_clicks_unique	integer	Unique link clicks	0	no	yes

Responses

Type	Description
array	An array that corresponds to the passed array, with the results. The array also contains the $batch_id string, the identifier for this import, which can be used in other API calls to check the progress of the import.

Code Samples

$json = '
{
"contacts":{
"1":{
"contact_email":"[email protected]",
"on_duplicate":"update",
"list_id":{"1":"subscribed"}
},
"2":{
"contact_email":"[email protected]",
"on_duplicate":"update",
"list_id":{"1234":"subscribed"},
"tags":["first tag name", "second tag name"]
}
}
}
';

$url = '(Your URL)/api/2.0/contacts/import';

$method = 'POST';

$cSession = curl_init();
$headers = array();
$auth = base64_encode($username . ':' . $apikey);
$headers[] = 'Authorization: Basic ' . $auth;
curl_setopt($cSession, CURLOPT_URL, $url);
curl_setopt($cSession, CURLOPT_RETURNTRANSFER, true);
curl_setopt($cSession, CURLOPT_HEADER, false);
curl_setopt($cSession, CURLOPT_CUSTOMREQUEST, strtoupper($method));
curl_setopt($cSession, CURLOPT_POSTFIELDS, $json);
$headers[] = 'Content-Type: application/json';
curl_setopt($cSession, CURLOPT_HTTPHEADER, $headers);
$result = curl_exec($cSession);
curl_close($cSession);