Contacts Import

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

API Method
RESTPOSThttp://[Your URL]/api/2.0/contacts/import
XML-RPCCallcontacts.ImportContacts
Your URL is the address of your Everlytic 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.

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. 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

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/import';

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 »