Description
This method enables you to create a new custom field directly via the API without having to create one from within the application.
Arguments
| Field | Description | Field Type | Required | Example | ||||||
|---|---|---|---|---|---|---|---|---|---|---|
| name | The name of the new custom field to be added. | string | Yes | Sign Up Date | ||||||
| type | The data type of the new custom field to be added. The values for this field include either of the following:
|
string | Yes | 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 must be defined as either of the following options:
If <type> is defined as string, the value of this element is set to "string". If <type> is defined as number, this element must contain two sub-elements where:
|
string | Conditional; Required only if <type> is defined as either date or number. |
DD/MM/YYYY | ||||||
| display_on_survey | A boolean value that defines whether the new custom field should be displayed in the standard survey web page (or the custom survey web page) where applicable. | boolean where:
NOTE: Numeric custom fields never appear in survey pages regardless of what value is passed here. |
No | 1 | ||||||
| friendly_tag | Defines the "friendly tag" name which is typically referenced within the email body for personalization. To view a list of existing friendly tag names within the application, log in and navigate to Assets > Manage Custom Fields and then look in the "Friendly Tag" column of the screen. | string | No | signupDate | ||||||
| default_value | Sets the default value of the new 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. | string | No | 01/01/2011 |
Response
| Field | Description | Example |
|---|---|---|
| responseCode | A code indicating either success or failure of the operation. (see Error Codes below) | 133 |
| responseText | Human readable description of the response code | This custom field has been added |
| id | If successful operation, this element will be set to the ID number identifying the newly added custom field. If unsuccessful operation, the value of this element will be zero. | 1055589 |
| name | The name of the custom field as provided by the input XML message. | Sign Up Date |
| type | The field type as provided by the input XML message. | date |
| format | The format as provided by the input XML message | DD/MM/YYYY |
| display_on_survey | A boolean value that defines whether the newly added custom field should be displayed in the standard survey web page (or the custom survey web page) where applicable, as provided by the input XML message. If unsuccessful operation, this element will be set to the default value of zero. | 1 |
| friendly_tag | The "friendly tag" name which is typically referenced within the email body for personalization as provided in the input XML message | signupDate |
| default_value | The default value of the new 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. |
Response Codes
| Error Condition | responseCode | responseText |
|---|---|---|
| Missing <format> element when the <type> element is set to "date". | 130 | action not taken, format required when type is date |
| The value for the <format> element is incorrect according to the specification. | 131 | action not taken, invalid format |
| The name of the custom field already exists. Field names must be unique | 132 | action not taken, field name already exists |
| Successful operation | 133 | this custom field has been added |
| Missing <format> element when the <type> element is set to "number". | 136 | action not taken, format required when type is number |
Example Post
<methodCall>
<methodname>account.addCustomField</methodname>
<name>Sign Up Date</name>
<type>date</type>
<format>DD/MM/YYYY</format>
<display_on_survey>1</display_on_survey>
<friendly_tag>signupDate</friendly_tag>
<default_value>01/01/2011</default_value>
</methodCall>
Example Response
<methodResponse>
<item>
<methodName><![CDATA[account.addCustomField]]></methodName>
<responseCode><![CDATA[133]]></responseCode>
<responseText><![CDATA[This custom field has been added]]></responseText>
<responseData>
<id><![CDATA[1055589]]></id>
<name><![CDATA[Sign Up Date]]></name>
<type><![CDATA[date]]></type>
<format><![CDATA[DD/MM/YYYY]]</format>
<display_on_survey><![CDATA[1]]></display_on_survey>
<friendly_tag><![CDATA[signupDate]]></friendly_tag>
<default_value><![CDATA[01/01/2011]]></default_value>
</responseData>
<responseNum><![CDATA[1]]></responseNum>
</item>
</methodResponse>
Example Error
<methodResponse>
<item>
<methodName><![CDATA[account.addCustomField]]></methodName>
<responseCode><![CDATA[132]]></responseCode>
<responseText><![CDATA[action not taken, field name already exists]]></responseText>
<responseData>
<id><![CDATA[0]]></id>
<name><![CDATA[Sign Up Date]]></name>
<type><![CDATA[date]]></type>
<format><![CDATA[DD/MM/YYYY]]></format>
<display_on_survey><![CDATA[1]]></display_on_survey>
<friendly_tag>![CDATA[signupDate]]></friendly_tag>
<default_value>![CDATA[01/01/2011]]></default_value>
</responseData>
<responseNum><![CDATA[1]]></responseNum>
</item>
</methodResponse>