account.addCustomField

‹ BACK TO API PAGE


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:
  • date
  • string
  • number
  • zip_code
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:
  • MM/DD/YYYY
  • DD/MM/YYYY
  • FMMonth ddth, YYYY (example: December 31st, 2010)
  • FMMonth ddth
  • YYYY-MM-DD

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:

Sub-element name Value
decimals Any digit between 0 and 9
separators Either of the following options:
  • 1234567.89
  • 1,234,567.89
  • 1 234 567,89
  • 1.234.567,89
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:
  • 0 – do not display (default)
  • 1 – display

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>


Back to API Reference Guide