addField

Adds a new Field to a List.

addField

Adds a new Field to a List.

Top ↑

Syntax

int addField( string api_key, int list_id, array field_details );

Parameters

api_key (string)

Key required to access the API. See Getting Started for more information.

list_id (int)

The ID of the List to add the Field to.

field_details (array)

An associative array of Field details. See remarks below for a description of the values in the field_details array.

Return Value

Returns the ID of the newly added Field on success.

Examples

The examples below create a text field, a drop-down list, a date Field, and a file upload Field.

Creating a mandatory text Field with show_in_form set to false.

$list_id = 1234567;     // can be obtained using searchLists

$text_field_details = array(
    'name'          => 'entry point',
    'type'          => 'text',
    'length'        => 30,
    'is_mandatory'  => true,
    'allow_update'  => false,
    'show_in_form'  => false
);

$api = new Api($url, 'YOURAPIKEY');
$text_field_id = $api->invokeMethod('addField', $list_id, $text_field_details);
{
    "id": 1,
    "method": "addField",
    "params": [
        "YOURAPIKEY",
        1234567,
        {
            "name": "entry point",
            "type": "text",
            "length": 30,
            "is_mandatory": true,
            "allow_update": false,
            "show_in_form": false
        }
    ]
}
{
    "id": 1,
    "result": 123456,
    "error": null
}

Creating a drop-down list with time_format set to 24h.

$dropdown_field_details = array(
    'name'               => 'State',
    'type'               => 'dropdown',
    'values_array'       => 'Please Select,Queensland,New South Wales,South Australia',
    'defaults_array'     => 'Please Select',
    'dont_store_default' => true,
    'time_format"        => '24h'
);

$api = new Api($url, 'YOURAPIKEY');
$dropdown_field_id = $api->invokeMethod('addField', $list_id, $dropdown_field_details);
{
    "id": 1,
    "method": "addField",
    "params": [
        "YOURAPIKEY",
        1234567,
        {
            "name": "State",
            "type": "dropdown",
            "is_mandatory": true,
            "allow_update": true,
            "show_in_form": true,
            "values_array": "Please Select,Queensland,New South Wales,South Australia",
            "defaults_array": "Please Select",
            "dont_store_default": true,
            "time_format": "24h"
        }
    ]
}
{
    "id": 1,
    "result": 123457,
    "error": null
}

Creating a date Field with a date_validation range and time_format set to 12h

$date_field_details = array(
    'name'              => 'Session Time',
    'type'              => 'date',
    'date_validation'   => '2012-10-18,2012-10-19', // between 18th & 19th October 2012
    'time_format'       => '12h',
    'default_value'     => '2012-10-18'
);

$api = new Api($url, 'YOURAPIKEY');
$date_field_id = $api->invokeMethod('addField', $list_id, $date_field_details);
{
    "id": 1,
    "method": "addField",
    "params": [
        "YOURAPIKEY",
        1234567,
        {
            "name": "Session Time",
            "type": "date",
            "date_validation": "2012-10-18,2012-10-19",
            "time_format": "12h",
            "default_value": "2012-10-18"
        }
    ]
}
{
    "id": 1,
    "result": 123458,
    "error": null
}

Creating a file upload Field. Note that row_size stores the maximum file size in megabytes.

$file_field_details = array(
    'name'               => 'Resume',
    'type'               => 'file',
    'allowed_file_types' => 'documents',
    'row_size'           => '1.5',       // set maximum file size to 1.5Mb
    'file_folder_id'     => 45678        // can be obtained using searchFolders()
);

$api = new Api($url, 'YOURAPIKEY');
$file_field_id = $api->invokeMethod('addField', $list_id, $file_field_details);
{
    "id": 1,
    "method": "addField",
    "params": [
        "YOURAPIKEY",
        1234567,
        {
            "name": "Resume",
            "type": "file",
            "allowed_file_types": "documents",
            "row_size": "1.5",
            "file_folder_id": 45678
        }
    ]
}
{
    "id": 1,
    "result": 123459,
    "error": null
}

Remarks

The following table shows the structure of the field_details array.

Key Type Mandatory Default Description
name string Yes The name of the Field in the List.
type string Yes The type of the Field. See below for a list of supported Field types.
allow_update bool No false Set to true to display the Field in update profile Forms by default.
allowed_file_types string No images, documents A comma separated list of allowed file types for file Fields. Can be one or more of images, documents, spreadsheets, movies or other.
date_validation string No past Validation for date Fields. Can be either past, future or a date range separated by a comma in ISO format (e.g. "1980-01-01,1999-12-31").
default_value string No The default value for text, comment, decimal, currency and date Fields. For date Fields can be set to current or a date in ISO format (e.g. "2001-03-17").
defaults_array string No The default value for drop-down list, radio and checkbox Fields. Use a comma separated list to specify multiple default values for checkbox Fields.
dont_store_default bool No false Set to true to prevent storing the default value for drop-down list Fields.
file_folder_id int No* Required for file Fields. Specifies the folder to contain the uploaded Files. See searchFolders.
is_mandatory bool No false Set to true to display the Field as mandatory in Web Forms by default. Note: The API does not check this value when adding/editing Contacts.
length int No 40 The maximum length for values stored in a text Field.
row_size string No 6 or 0.5 For comment Fields, this is the number of rows to display. For file Fields, this is the maximum allowed file size in megabytes and defaults to 0.5 Mb. The system allows a maximum file size of 15 Mb.
show_in_form bool No false Set to true to display the Field in subscription Forms by default.
time_format string No off The format of the time part of a date Field. Can be one of off, 12h, or 24h.
values_array string No A comma separated list of values for drop-down list, radio and checkbox Fields.

Field Types

The method supports creating Fields with the following field types:

Field Type Description
text Plain text field that can be used for any type of data.
currency Money values.
decimal Decimal field for any type of number, quantity, age, etc. Can be searched numerically.
comment Text block. Use for descriptions, comments, or requests.
dropdown Drop-down list that allows user to choose a single selection from a list of items.
checkbox Checkbox control. Allows user to select multiple items.
radio Radio button control. Allows users to select one item.
file File upload control. The uploaded File is stored in the File Manager. The system supports a maximum file upload size of 15Mb.
date Date control. Allows user to select a date from a calendar pop-up or enter a date manually.

Error Codes

This method may return the following error codes in addition to the standard error codes:

Code Error Description
303 Unable to Load List list_id is not a valid List
318 Duplicate Field Name Another Field with the same name already exists in the List
325 Field Name is Reserved or Invalid name is a reserved word or the name of a system field ("id", "timestamp", "mandatory" etc)
310 Invalid Method Parameters: Default value must be a number You are creating a decimal or currency Field, but you have not entered a number for default_value
369 File field must be associated with a File Folder You are creating a File Field, but file_folder_id is invalid or not supplied.
306 Unable to Load Folder file_folder_id is not a valid Folder
368 Folder is not a file folder file_folder_id is not a file Folder
310 Invalid Method Parameters: Invalid time format time_format is invalid. Must be one of "off", "12h", or "24h".
310 Invalid Method Parameters: Invalid default date You are creating a date field, but default_value is not a valid date. Date must be in ISO format (e.g. "2001-03-17").
310 Invalid Method Parameters: Expected comma separated date range date_validation is not a comma separated date range
310 Invalid Method Parameters: Invalid minimum validation date The minimum date value specified in date_validation is not a valid date
310 Invalid Method Parameters: Invalid maximum validation date The maximum date value specified in date_validation is not a valid date
310 Invalid Method Parameters: Invalid date range The minimum date must be less than the maximum date in date_validation
310 Invalid Method Parameters: Default date outside valid range The date specified in default_value must be a date in the range specified in date_validation
310 Invalid Method Parameters: Invalid field type type is not a valid Field type
302 Undefined Error An internal error occurred while trying to create the Field

See Also

Method References
Popular Pages