API Custom Fields | Knowledge Base

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

Type	Request	Method	Description
REST	POST	https://[Your URL]/api/2.0/contacts
XML-RPC	Call	contacts.CreateContact	Pass the correct data with this function.

Your URL is the address of your 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.

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	yes	no
mobile	string	Mobile	empty	yes	no

Optional Parameters

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

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
integer	The ID of the updated contact.

Custom Field Code

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

$json = '
{
"name":"My first name",
"lastname":"My lastname",
"email":"[email protected]",
"gender":"gender",
"date_of_birth":"1234560000000",
"mobile":"123456789",
"cfv_textfield67":"insert text here."&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
"on_duplicate":"update",
"list_id":{"1234":"subscribed"}
}
';
$url = '(Your URL)/api/2.0/contacts';
$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);

Multi-value Custom Field Code

The code would be similar to this:

$json = '
{
"name":"My first name",
"lastname":"My lastname",
"email":"[email protected]",
"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"}
}
';
$url = '(Your URL)/api/2.0/contacts';
$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);