Create a New Contact

This request allows you to create a new contact. You'll do this when you want to add a contact to one or more of your lists.

Requests to create duplicate contacts (as determined by the email address and the mobile number of the contact) will fail. This can be changed to update the current contact with the latest information by setting the on_duplicate property to 'update'. Please note that the API will return a 201 Created HTTP response for updates.


The Method

API MethodDetails
RESTPOSThttp://[Your URL]/api/2.0/contacts
XML-RPCCallcontacts.CreateContactPass the correct data with this function.
Your URL is the address of your Everlytic install.

Your method must be structured as follows:

CreateContact(\struct | array $properties) : int

Parameters

Required Parameters

You must, at the very least, have either an email address or a mobile phone number when you create a new contact. You must also specify the lists the contact will belong to, and their subscription status.

PropertyTypeDescriptionDefaultRequiredRead Only
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
emailstringEmailemptyyesno
mobilestringMobileemptyyesno

Optional Parameters

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

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
integerThe ID of the created contact.

Code Samples

PHP (Using the 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 the variable at the top of the API request (above the URL section).

$json = '

{

"name":"My first name",

"lastname":"My lastname",

"email":"michael@everlytic.com",

"gender":"male",

"date_of_birth":"371430000000",

"mobile":"123456789",

"on_duplicate":"update",

"list_id":{"1234":"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';

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 the 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 variable 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 »