Create custom fields - ExpertSender Help Center

Fields collection allows creating one or more new custom fields. Attempting to add a field that already exists will end with an error message about a duplicate custom field.

Request data format

Data part of request for creating one or more new custom field.

Element/attribute	Type	Notes
apiKey	string	Your API key, required for authentication. Required.
Data	complex	Field element. Only if adding only one custom field.
MultiData	array[complex]	Array of fields elements. Only if adding more than one custom fields.

Data element children:

Element/attribute	Type	Notes
Name	string	Custom field name.
FriendlyName	string	Custom field „friendly” name for display purposes.
Type	string	Custom field type. One of: Text, Number, Money, Date, Datetime, SingleSelect, Boolean, Url.
DefaultValue	mixed	Custom field default value. Content depends on field type. Optional. *
Description	string	Text description of custom field. Optional.
Visible	boolean	True, if custom field is visible to subscribers in e.g. Preference Center.
Required	boolean	True, if custom field is required when subscribing to a list.
Options	array[complex]	Array of options for single select field.

MultiData part of request for creating new custom fields.

MultiData element children:

Element/attribute	Type	Notes
Fields	array[complex]	Array of Field elements.

Field element children:

Element/attribute	Type	Notes
Name	string	Custom field name.
FriendlyName	string	Custom field „friendly” name for display purposes.
Type	string	Custom field type. One of: Text, Number, Money, Date, Datetime, SingleSelect, Boolean, Url.
DefaultValue	mixed	Custom field default value. Content depends on field type. Optional. *
Description	string	Text description of custom field. Optional.
Visible	boolean	True, if custom field is visible to subscribers in e.g. Preference Center.
Required	boolean	True, if custom field is required when subscribing to a list.
Options	array[complex]	Array of options for single select field.

Option element children:

Element/attribute	Type	Notes
FriendlyName	string	Custom field „friendly” name for display purposes.
Value	string	Custom field value.

* xsi:type should correspond with property type. Providing incorrect value type will result in an error. See the table below for details:

Property type	Allowed xsi:type	Example values
Text	xsd:string	this is a test, foobar
Number	xsd:integer	12345
Money	xsd:decimal, xsd:integer	123.45, 123
Date	xsd:date	1985-03-12 **
Datetime	xsd:dateTime, xsd:date	1985-03-12T12:00:00
Boolean	xsd:boolean	true, false, 1, 0
Url	xsd:string	http://www.domain.com/page.html
SingleSelect	xsd:string	value1, value2, M, F*

* Single select property will accept only one of predefined values for this particular property.

** Format: YYYY-MM-DD

Response

Method for adding custom field returns name and ID of created field.

Response Data element:

Element/attribute	Type	Notes
Name	string	Name of added custom field.
Id	int	ID of added custom field.

Response MultiData element:

Element/attribute	Type	Notes
Data	array[complex]	Array of field data elements.

Field data element children:

Element/attribute	Type	Notes
Name	string	Name of added custom field.
Id	int	ID of added custom field.

Examples

Request for adding custom field:

POST https://api.esv2.com/v2/Api/Fields HTTP/1.1 
Accept-Encoding: gzip,deflate 
Content-Type: application/xml 
User-Agent: Jakarta Commons-HttpClient/3.1 
Host: api.esv2.com 
Content-Length: 411 

<ApiRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <ApiKey>test_api_key1</ApiKey>
  <Data>
    <Name>example_name</Name>
    <FriendlyName>example_friendly_name</FriendlyName>
    <Type>Text</Type>
    <DefaultValue xsi:type="xsd:string">example</DefaultValue>
    <Description>description</Description>
    <Visible>true</Visible>
    <Required>false</Required>
  </Data>
</ApiRequest>

OK response:

HTTP/1.1 200 OK
Cache-Control: private
Content-Type: text/xml; charset=utf-8
Server: Microsoft-IIS/7.5
X-AspNetMvc-Version: 5.2
X-AspNet-Version: 4.0.30319
Set-Cookie: TEMP_DATA=c0d53e6c-d043-474f-b899-c7bc080f637d; path=/
X-Powered-By: ASP.NET
Date: Mon, 02 Feb 2015 17:06:10 GMT
Content-Length: 1877

<ApiResponse xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <Data>
    <Name>example_name</Name>
    <Id>1</Id>
  </Data>
</ApiResponse>

Request for adding custom fields:

POST https://api.esv2.com/v2/Api/Fields HTTP/1.1 
Accept-Encoding: gzip,deflate 
Content-Type: application/xml 
User-Agent: Jakarta Commons-HttpClient/3.1 
Host: api.esv2.com 
Content-Length: 411 

<ApiRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<ApiKey>{{ApiKey}}</ApiKey>
  <MultiData>
    <Field>
      <Name>example_name</Name>
      <FriendlyName>example_friendly_name</FriendlyName>
      <Type>Text</Type>
      <DefaultValue xsi:type="xsd:string">example</DefaultValue>
      <Description>description</Description>
      <Visible>true</Visible>
      <Required>false</Required>
    </Field>
    <Field>
      <Name>example_name1</Name>
      <FriendlyName>example_friendly_name1</FriendlyName>
      <Type>Number</Type>
      <DefaultValue xsi:type="xsd:int">123</DefaultValue>
    </Field>
    <Field>
      <Name>example_name2</Name>
      <FriendlyName>example_friendly_name2</FriendlyName>
      <Type>Date</Type>
      <DefaultValue xsi:type="xsd:date">2023-10-12</DefaultValue>
      <Description>description</Description>
      <Visible>true</Visible>
    </Field>
    <Field>
      <Name>example_name3</Name>
      <FriendlyName>example_friendly_name3</FriendlyName>
      <Type>Datetime</Type>
      <DefaultValue xsi:type="xsd:dateTime">2023-10-12T00:00:00Z</DefaultValue>
    </Field>
    <Field>
      <Name>example_name4</Name>
      <FriendlyName>example_friendly_name4</FriendlyName>
      <Type>SingleSelect</Type>
      <DefaultValue xsi:type="xsd:string">option1</DefaultValue>
      <Description>description</Description>
      <Required>false</Required>
      <Options>
                <Option>
                    <Value>option1</Value>
                    <FriendlyName>Opcja 1</FriendlyName>
                </Option>
                <Option>
                    <Value>option2</Value>
                    <FriendlyName>Opcja 2</FriendlyName>
                </Option>
                </Options>
    </Field>
    <Field>
      <Name>example_name5</Name>
      <FriendlyName>example_friendly_name5</FriendlyName>
      <Type>Boolean</Type>
      <DefaultValue xsi:type="xsd:boolean">1</DefaultValue>
      <Required>false</Required>
    </Field>
    <Field>
    <Name>example_name6</Name>
      <FriendlyName>example_friendly_name6</FriendlyName>
      <Type>Money</Type>
      <DefaultValue xsi:type="xsd:decimal">99.99</DefaultValue>
      <Required>false</Required>
    </Field>
    <Field>
    <Name>example_name7</Name>
      <FriendlyName>example_friendly_name7</FriendlyName>
      <Type>Url</Type>
      <DefaultValue xsi:type="xsd:string">https://expertsender.com</DefaultValue>
      <Required>false</Required>
    </Field>
  </MultiData>
</ApiRequest>

Created response:

HTTP/1.1 201 Created
Cache-Control: private
Content-Type: text/xml; charset=utf-8
Server: Microsoft-IIS/7.5
X-AspNetMvc-Version: 5.2
X-AspNet-Version: 4.0.30319
Set-Cookie: TEMP_DATA=c0d53e6c-d043-474f-b899-c7bc080f637d; path=/
X-Powered-By: ASP.NET
Date: Mon, 02 Feb 2015 17:06:10 GMT
Content-Length: 1877

<ApiResponse xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <Data>
        <FieldData>
            <Name>example_name</Name>
            <Id>1</Id>
        </FieldData>
        <FieldData>
            <Name>example_name1</Name>
            <Id>2</Id>
        </FieldData>
        <FieldData>
            <Name>example_name2</Name>
            <Id>3</Id>
        </FieldData>
        <FieldData>
            <Name>example_name3</Name>
            <Id>4</Id>
        </FieldData>
        <FieldData>
            <Name>example_name4</Name>
            <Id>5</Id>
        </FieldData>
        <FieldData>
            <Name>example_name5</Name>
            <Id>6</Id>
        </FieldData>
        <FieldData>
            <Name>example_name6</Name>
            <Id>7</Id>
        </FieldData>
        <FieldData>
            <Name>example_name7</Name>
            <Id>8</Id>
        </FieldData>
    </Data>
</ApiResponse>

Bad Request response:

HTTP/1.1 400 Bad Request
Cache-Control: private
Content-Type: text/xml; charset=utf-8
Server: Microsoft-IIS/7.5
X-AspNetMvc-Version: 5.2
X-AspNet-Version: 4.0.30319
Set-Cookie: TEMP_DATA=c0d53e6c-d043-474f-b899-c7bc080f637d; path=/
X-Powered-By: ASP.NET
Date: Mon, 02 Feb 2015 17:06:10 GMT
Content-Length: 1877

<ApiResponse xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <Data>
    <FieldData>
      <Name>example_name</Name>
      <Id>1</Id>
    </FieldData>
    <FieldData>
      <Name>example_name1</Name>
      <Error>DefaultValue is invalid. Make sure default field value fits its Type.</Error> 
    </FieldData>
    <FieldData>
      <Name>example_name2</Name>
      <Error>FriendlyName is required.</Error> 
    </FieldData>
    <FieldData>
      <Name>example_name2</Name>
      <Error>Values for single select options must be unique.</Error>  
    </FieldData>
    <FieldData>
      <Name>example_name2</Name>
      <Error>Custom field with the same Name already exists.</Error>  
    </FieldData>
  </Data>
</ApiResponse>