Description
This method returns all the custom fields created for your account. Using the input parameters, you can control how many fields to return in the response message, and the offiset to skip in the numerical order. This latter input parameter is useful when you are building a user interface displaying all your custom fields that includes paging. Rather than pull the complete set of custom fields, you can only pull the ones you need depending upon which page the user is viewing in the interface.
The collection of custom fields is encapsulated within the <custom_fields> element. The details of each custom field are in turn, encapsulated within the <item> element. Hence:
<custom_fields>
<item>
… custom field elements
</item>
<item>
… custom field elements
</item>
… additional custom fields
</custom_fields>
The list of fields will be ordered by field name in alphabetical order.
Arguments
| Field | Description | Field Type | Required | Example |
|---|---|---|---|---|
| limit | A numeric value specifying how many custom field records will be included in the response message. | string | No | 25 |
| offset | A numeric value specifying how many custom field records to skip from the response. Use this element when you are using this API to construct a user interface that displays the complete list of custom fields over several "pages". | string | No | 26 |
Response
| Field | Description | Example | ||||||
|---|---|---|---|---|---|---|---|---|
| responseCode | A code indicating either success or failure of the operation. (see Error Codes below) | 160 | ||||||
| responseText | Human readable description of the response code | displaying all custom fields | ||||||
| id | The ID number assigned to the custom field. | 1055589 | ||||||
| name | The display name of the custom field. | Sign Up Date | ||||||
| type | The data type of the custom field. Data types include any of the following:
|
date | ||||||
| format | This element is used to define how the field value will be displayed within the body of an email when used as a personalization tag. What appears in this element depends upon the <type>If <type> is defined as date, the value of this element will be defined as either of the following options:
If <type> is defined as string, the value of this element will be set to "string". If <type> is defined as number, this element will contain two sub-elements where:
|
DD/MM/YYYY | ||||||
| display_on_survey | A boolean value that defines whether the custom field should be displayed in the standard survey web page (or the custom survey web page) where applicable. | 1 | ||||||
| friendly_tag | The "friendly tag" name which is typically referenced within the email body for personalization. | signupDate | ||||||
| system_tag | The system-assigned name which is referenced internally within the email body for personalization. | custom23 | ||||||
| default_value | The default value of the custom field that is displayed within the body of the email when the subscriber's contact record does not include a value for this custom field. | 01/01/2011 | ||||||
| wm_trigger | A boolean value indicating whether this custom field is set as the Welcome Message field trigger. | 1 | ||||||
| doi_trigger | A boolean value indicating whether this custom field is set as the double opt-in field trigger. | 0 |
Response Codes
| Error Condition | responseCode | responseText |
|---|---|---|
| Successful operation; all custom fields in the system are returned with no offset or limit. | 160 | Displaying all custom fields |
| There are fewer custom fields in the system than specified by the <offset> parameter. | 161 | Offset exceeds number of custom fields |
| There are no custom fields in the system to return | 162 | No custom fields returned |
| Successful operation; the subset of custom fields defined by the limit and offset are returned | 163 | Retrieved subset of custom fields |
Example Post
<methodCall>
<methodName>account.getCustomFields</methodName>
<limit>2</limit>
<offset>5</offset>
</methodCall>
Example Response
<methodResponse>
<item>
<methodName>account.getCustomFields</methodName>
<responseCode>163</responseCode>
<responseText>Retrieved subset of custom fields</responseText>
<responseData>
<custom_fields>
<item>
<name>Favorite Color</name>
<id>1477174</id>
<type>string</type>
<format>string</format>
<friendly_tag>cf_favColor</friendly_tag>
<system_tag>custom6</system_tag>
<default_value>Blue</default_value>
<display_on_survey>1</display_on_survey>
<wl_trigger>1</wl_trigger>
<doi_trigger>0</doi_trigger>
</item>
<item>
<name>Birthday</name>
<id>1574329</id>
<type>date</type>
<format>MM/DD/YYYY</format>
<friendly_tag>cf_birthday</friendly_tag>
<system_tag>custom7</system_tag>
<default_value>your upcoming birthday</default_value>
<display_on_survey>1</display_on_survey>
<wl_trigger>0</wl_trigger>
<doi_trigger>0</doi_trigger>
</item>
</custom_fields>
</responseData>
<responseNum>1</responseNum>
</item>
</methodResponse>
Example Error
<methodResponse>
<item>
<methodName>account.getcustomfields</methodName>
<responseCode>161</responseCode>
<responseText>Offset exceeds number of custom fields</responseText>
<responseData></responseData>
<responseNum>1</responseNum>
</item>
</methodResponse>