BrandMail API - editField

Syntax

int editField( 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 containing the Field.
field_details (array): An associative array of Field details to be edited. See remarks below for a description of the values in the field_details array.

Return Value

Returns the ID of the edited Field on success.

Examples

The following code sets the name of the Field 2345678 to Template in the List 1234567.

$list_id = 1234567;     // See searchLists()

$field_details = array(

    'id'    => 2345678,     // See searchFields()

    'name'  => 'Template'

);

$api = new Api($url, 'YOURAPIKEY');

$field_id = $api->invokeMethod('editField', $list_id, $field_details);

{

    "id": 1,

    "method": "editField",

    "params": [

        "YOURAPIKEY",

        1234567,

        {

            "id": 2345678,

            "name": "Template"

        }

    ]

}

{

    "id": 1,

    "result": 2345678,

    "error": null

}

Remarks

The following table shows the structure of the field_details array.

Key	Type	Mandatory	Description
`id`	int	Yes	ID of the Field.
`name`	string	No	The name of the Field in the List.
`allow_update`	bool	No	Set to `true` to display the Field in update profile Forms by default.
`allowed_file_types`	string	No	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	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	Set to `true` to prevent storing the default value for drop-down list Fields.
`file_folder_id`	int	No	Specifies the folder to contain the uploaded Files. See searchFolders.
`is_mandatory`	bool	No	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	The maximum length for values stored in a text Field.
`row_size`	string	No	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	Set to `true` to display the Field in subscription Forms by default.
`time_format`	string	No	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.

The method can only be used to edit Fields which have one of the supported Field types (see addField).

Converting an existing Field to a different type is not supported.

Error Codes

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

Code	Error	Description
`310`	Invalid Method Parameters	`id` is empty or missing from the `field_details` array
`303`	Unable to Load List	`list_id` is not a valid List
`305`	Unable to Load Field	`id` is not a valid Field 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)
`318`	Duplicate Field Name	Another Field with the same `name` already exists in the List
`310`	Invalid Method Parameters: Default value must be a number	`default_value` is not a number when editing a decimal or currency Field
`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	`default_value` is not a valid date when creating a date field. Must be a date 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` when editing a date Field
`310`	Invalid Method Parameters: Invalid field type	Editing a Field of this type is not supported
`302`	Undefined Error	An internal error occurred.

editField