BrandMail API - searchFields

Syntax

array searchFields(
    string api_key,
    int list_id,
  [ array search_criteria,
    int limit,
    int offset,
    string sort_by,
    string sort_order ] 
);

Parameters

api_key (string)

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

list_id (int)

The ID of the List.

search_criteria (array - optional)

An array of search criteria. See the remarks section below for the list of values which are searchable.
If you do not specify search criteria, all Fields in the List are returned.

limit (int - optional)

Maximum number of items to return.

offset (int - optional)

Number of items to skip before beginning to return results. See Using Search Methods for information about using the offset parameter with the limit parameter to include pagination in your results.

sort_by (string - optional)

The name of the value to sort the results by.

sort_order (string - optional)

The order the results are returned in (either ascending or descending). The default is descending. Valid values are:

DESC - Sort from highest to lowest (default).
ASC - Sort from lowest to highest.

Return Value

Returns an array containing zero or more associative arrays of Field details. See the remarks section below for the list of values this method returns.

Examples

The following example searches for all mandatory dropdown Fields in List 1234567. Note that the two search criteria are ANDed.

$list_id = 1234567;     // see searchLists()

$search_criteria = array(

    array('is_mandatory', 'exactly', '1'),

    array('type', 'exactly', 'dropdown')

);

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

$fields = $api->invokeMethod('searchFields', $list_id, $search_criteria);

// loop over result

foreach ($fields as $field_details) {

    print "Found ". $field_details['name'] ." Field\n";

}

{

    "id": 1,

    "method": "searchFields",

    "params": [

        "YOURAPIKEY",

        1234567,

        [

            ["is_mandatory", "exactly", "1"],

            ["type", "exactly", "dropdown"]

        ]

    ]

}

{

    "id":1,

    "result":[

        {

            "id": 2345678,

            "list_id": 1234567,

            "name": "State",

            "type": "dropdown",

            "is_mandatory": true,

            "allow_update": false,

            "show_in_form": 0,

            "length": 0,

            "size": 0,

            "row_size": 4,

            "default_value": "",

            "values_array":"Select...,Australian Capital Territory,New South Wales,Northern Territory,Queensland,South Australia,Tasmania,Victoria,Western Australia",

            "defaults_array": "",

            "dont_store_default": 0,

            "allowed_file_types": "",

            "file_folder_id": 0,

            "address_type": "none",

            "time_format": "",

            "date_validation": "",

            "display_order": 2

        }

    ],

    "error": null

}

Remarks

The following table shows the values that are returned.

Key	Type	Searchable	Description
`id`	int	Yes	The ID of the Field.
`list_id`	int	No	The ID of the List the Field is in.
`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.
`address_type`	string	Yes	The address type for address Fields. Valid values are `email`, `mobile` or `none`.
`allow_update`	bool	Yes	A value indicating whether the Field is displayed in update profile Forms by default.
`allowed_file_types`	string	Yes	A comma separated list of allowed file types for file Fields. Can be one or more of `images`, `documents`, `spreadsheets`, `movies` or `other`.
`default_value`	string	Yes	The default value for text, comment, decimal, currency and date Fields. For date Fields can be `current` or a date in ISO format (e.g. "2001-03-17").
`dont_store_default`	bool	Yes	A value indicating whether the default value is stored in dropdown Fields.
`file_folder_id`	int	Yes	The ID of the Folder where Files are uploaded to for file fields.
`is_mandatory`	bool	Yes	A value indicating whether the Field is displayed as mandatory in Web Forms by default.
`show_in_form`	bool	Yes	A value indicating whether the Field is displayed in subscription Forms by default.
`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").
`defaults_array`	string	No	The default value for drop-down list, radio and checkbox Fields.
`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.
`time_format`	string	No	The format of the time part of a date Field. Valid values are `off`, `12h`, or `24h`.
`values_array`	string	No	A comma separated list of values for drop-down list, radio and checkbox Fields.
`display_order`	int	No	A value indicating the Field order on the default Webform for the List. A value of -1 indicates the field is hidden.

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
`311`	Invalid Search Parameter Format	`search_critera` is not valid

searchFields