listMergeVarAdd()

This function adds a new merge field to a particular list in the database adding also the name and settings of this field.

listMergeVarAdd(string $id, string $tag, string $name, array $options) : boolean

Input parametrs

• id - list ID
• tag - merge field tag name. Used in forms and also in API functions such as listSubscribe and listUpdateMember
• name - user friendly name
• options - settings of a field (optional). Array consisting of:
• field_type - field type of merge tag (text, number, radio, grouping, dropdown, date, address, sms, website, image) (optional). Default value is text.
  Important adding data to date field type use the following format: YYYY-MM-DD, e.g., 2015-09-30 See API functions listSubscribe and listUpdateMember for adding data to merge fields.
• req - required (true, false) (optional). Default value is false.
• show - whether this field is shown in the list (true, false) (optional). Default value is true.
• pubilc - whether this field is shown in the web signup forms (true, false) (optional). Default value is true.
• default_value - default value of merge tag (optional).
• predefined_values - user predefined custom field values for radio, grouping and dropdown field types (optional).
  Important 

  • Two vertical lines (||) are used as a value separator. E.g.,

    Male||Female||Prefer not to say

  • Array of values and labels can be used as well. E.g.,

    array('values' => array('M', 'F'), 'labels' => array('Male', 'Female'))

Information obtained

Array of merge fields. Each merge field is represented as an array that includes:

• true, if request for field creation has succeeded.

Examples

mgapi_listMergeVarAdd.php

 'text',
    "req" => false,
    "default_value" => 'Default value',
    "show" => true
);
 
$retval = $api->listMergeVarAdd($id, $tag, $name, $options);
 
header("Content-Type: text/plain");
if ($api->errorCode) {
    echo "Unable to load listMergeVarAdd()!\n";
    echo "\tCode=" . $api->errorCode . "\n";
    echo "\tMsg=" . $api->errorMessage . "\n";
} else {
    echo "Returned: " . $retval . "\n";
}

xml-rpc_listMergeVarAdd.php

 new xmlrpcval($apikey),
                    'id' => new xmlrpcval($listId),
                    'tag' => new xmlrpcval('MERGE_TAG'),
                    'name' => new xmlrpcval('Merge Tag name'),
                    'options' => php_xmlrpc_encode(
                            array(
                                "field_type" => 'text',
                                "req" => false,
                                "default_value" => 'Default value',
                                "show" => true
                            )
                    )
                ),
                'struct');
$f = new xmlrpcmsg('listMergeVarAdd', array($v));
$c = new xmlrpc_client($apiUrl["path"], $apiUrl['host'], 80);
$c->setDebug($debug);
$r = &$c->send($f);
 
header("Content-Type: text/plain");
if (!$r->faultCode()) {
    $retval = php_xmlrpc_decode($r->value());
    echo "Returned: " . $retval . "\n";
} else {
    echo "Unable to load listMergeVarAdd()!\n";
    echo "\tCode=" . $r->faultCode() . "\n";
    echo "\tMsg=" . $r->faultString() . "\n";
}

mgapi_listMergeVarAdd.py

from lib.config import * #contains apikey
from lib.MGAPI import MGAPI
 
# This Example shows how to ping using the MGAPI.php class and do some basic error checking.
 
api = MGAPI(apikey)
 
id = listId
tag = 'MERGE_TAG'
name = 'Merge Tag name'
options = {
    "field_type": 'text',
    "req": False,
    "default_value": 'Default value',
    "show": True
}
 
retval = api.listMergeVarAdd(id, tag, name, options)
if api.errorCode:
    print "Unable to load listMergeVarAdd()!"
    print "\tCode=", api.errorCode
    print "\tMsg=", api.errorMessage
else:
    print "Returned: ", retval