API Custom Fields

Overview

The API is a Web Service through which clients can access and manipulate their accounts. Custom fields and multi-value custom fields can now be incorporated into the API for all contact requests.


Custom Fields

Custom fields can now be included in the Create Contact API request. Requirements are the list ID, email status, and both the sanitized name and custom field name as it appears in the product.

Multi-value Custom Fields

Multi-value custom fields appear as regular custom fields, and will therefore follow the same format. The only difference will be each option appearing as a separate custom field.

The request is used to create a new contact, with the custom fields included in the request. The request will require a Method, Parameter, and Response as follows:

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.

Custom Field Code

The code to create a new contact with the custom field included will look similar to this:

Custom Field Code Breakdown

The example above is broken down step-by-step. Let's analyse the code sample above to determine where each line fits into this outline.

RequestStructure

1. JSON

We use JSON to enclose the the variable at the top of the API request (above the URL section). Note the custom field included in the code:

$json = '

{

"name":"My first name",

"lastname":"My lastname",

"email":"name@company.com",

"gender":"gender",

"date_of_birth":"1234560000000",

"mobile":"123456789",

"cfv_textfield67":"insert text here."

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

Multi-value Custom Field Code

The code would be similar to this:


Custom Field Code Breakdown

The example above is broken down step-by-step. Let's analyse the code sample above to determine where each line fits into this outline.

RequestStructure

1. JSON

We use JSON to enclose the the variable at the top of the API request (above the URL section). Note the custom field included in the code:

$json = '

{

"name":"My first name",

"lastname":"My lastname",

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

"gender":"male",

"date_of_birth":"371430000000",

"mobile":"123456789",

"name":"Author",

"cfv_author12":"True"

"cfv_blogger22":"False"

"cfv_editor96":"False"

"cfv_reader95":"True"

"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 »