Create Contacts in Bulk

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

API MethodDetails
RESTPOSThttp:/[Your URL]/api/2.0/contacts/bulk
XML_RPCCallcontacts.BulkCreateContactsPass the correct data with this function.
Your URL is the address of your Everlytic 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.

PropertyTypeDescriptionDefaultRequiredRead Only
emailstringEmailemptynono
list_idarrayAn 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.
emptyyesno
mobilestringMobileemptynono

Optional Parameters

PropertyTypeDescriptionDefaultRequiredRead Only
country_idintegerCountry identifier1nono
city_idintegerCity identifier1nono
namestringFirst nameemptynono
lastnamestringLast nameemptynono
statusstringStatus
Possible values:
on
off
suppressed
onnono
preferred_email_formatstringEmail format
Possible values:
html
text
HTMLnono
titlestringTitleemptynono
company_positionstringPositionemptynono
company_namestringCompany nameemptynono
departmentstringDepartmentemptynono
industrystringIndustryemptynono
addressstringAddressemptynono
citystringCityemptynono
countrystringCountryemptynono
statestringProvince/stateemptynono
zipstringPostal/ZIP codeemptynono
telephone_officestringWork numberemptynono
telephone_homestringHome numberemptynono
telephone_faxstringFax numberemptynono
date_of_birthintegerDate of birth (deprecated)emptynono
birth_datestringDate of birthemptynono
genderstringGender
Possible variables:
unknown
male
female
emptynono
marital_statusstringMarital status
Possible values:
unknown
single
married
emptynono
education_levelstringEducation levelemptynono
hashstringhash_keyemtpynono
unique_idstringUnique import identifieremptynono
idintegerIDemptynoyes
date_createintegerDate createdemptynoyes
scorefloatContact score2noyes
ratingintegerContact score2noyes
email_statusstringEmail status
Possible values:
none
bouncing
bounced
always send
nonenoyes
create_notificationsstringCreate notification
Possible values:
yes
no
nonono
sms_statusstringSMS status
Possible values:
none
bouncing
bounced
always send
nonenoyes
email_bounce_hard_countintegerHard email bounces0noyes
email_bounce_soft_countintegerSoft email bounces0noyes
block_bounce_countintegerConsecutive block bounces0noyes
sms_bounce_hard_countintegerHard SMS bounces0noyes
sms_bounce_soft_countintegerSoft SMS bounces0noyes
sms_bounce_consecutive_countintegerConsecutive SMS bounces0noyes
complaints_countintegerComplaints0noyes
forward_countintegerForwardsemptynoyes
invite_countintegerInvitesemptynoyes
update_countintegerUpdates0noyes
bounce_unidentified_countintegerUnidentified bounces0noyes
autoresponder_countintegerAutoresponders0noyes
email_message_idsstringEmail message identifiersemptynoyes
sms_message_idsstringSMS message identifiersemptynoyes
email_message_countintegerEmail Messages0noyes
sms_message_countintegerSMS Messages0noyes
message_readsintegerReads0noyes
message_reads_inferredintegerInferred reads0noyes
message_reads_uniqueintegerUnique reads0noyes
message_link_clicksintegerLink clicks0noyes
message_link_clicks_uniqueintegerUnique link clicks0noyes

Responses

TypeDescription
arrayAn array that corresponds to the passed array, with the results.

Code Samples

PHP (using REST API)

Tutorial

The rest of this document describes the example above, step-by-step.

In our Getting Started section we covered the four important components of an API request; URL, method, headers, and body.

RequestStructure

Let's analyse the code sample above to determine where each line fits into this outline.

1. JSON

We use JSON to enclose the variables at the top of the API request (above the URL section).

$json = '

{

"contacts":{

"1":{

"contact_email":"michael1@everlytic.com",

"on_duplicate":"update",

"list_id":{"1":"subscribed"}

},

"2":{

"contact_email":"michael2@everlytic.com",

"on_duplicate":"update",

"list_id":{"1":"subscribed"}

}

}

}

';

2. Load the Everlytic API

The following line of code tells the server which API URL to access for the request:

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

Your URL is the URL of your Everlytic installation.

3. Method

In this line of code, you tell the API which REST function to use:

$method = 'POST';

4. cURL

cURL is a tool for sending and receiving files from a web server. This line of code initialises the cURL session.

$cSession = curl_init();

5. Initiate the Headers

This section of the code opens the headers section and passes the authentication (including your API key).

$headers = array();

$auth = base64_encode($username . ':' . $apikey);

$headers[] = 'Authorization: Basic ' . $auth;

6. Set various cURL options for the session

These lines of code tell the server that we're using cURL to transfer data.

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);

7. Tell the server to read the variables from the JSON string

$headers[] = 'Content-Type: application/json';

curl_setopt($cSession, CURLOPT_HTTPHEADER, $headers);

8. Output the API response

$result = curl_exec($cSession);

9. Close the cURL session

curl_close($cSession);
Translate »