Create Contacts in Bulk | Knowledge Base

Overview

You can use this request to create many contacts at once by passing an array of contacts to the server. Each contact’s details should be indexed by a separate array key. You can only create up to 2,000 contacts at once this way.

The API will return a 201 Created HTTP response if all contacts were created successfully. If some of the contacts failed, a 200 successful request response is returned, which contains information about each contact. For contacts that were not successfully created, details of the error will be returned for that specific contact.

The Method

Legend	Description
On	Contact is set to receive mail sent to all lists they’re subscribed to.
Off / Suppressed	Contact has complained and will not receive mail sent to any lists they’re on.
Awaiting Confirmation	The contact has been sent a confirmation mail but has not clicked the confirmation link.
Subscribed	The contact is subscribed and will receive mails sent to that list.
Unsubscribed	The contact has unsubscribed from that list and will not receive emails sent to that list.
Bounced	Mails sent to this contact have exceeded the bounce limit. Contacts that are bounced won’t be sent any mails on that list.

Your URL is the address of your install.

Your method must be structured as follows:

BulkCreateContacts(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

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.

Code Samples

PHP (using REST API)

$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/bulk';
$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);