Skip to content

Create custom fields

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/attributeTypeNotes
apiKeystringYour API key, required for authentication. Required.
DatacomplexField element. Only if adding only one custom field.
MultiDataarray[complex]
Array of fields elements. Only if adding more than one custom fields.

Data element children:

Element/attributeTypeNotes
NamestringCustom field name.
FriendlyNamestringCustom field “friendly” name for display purposes.
TypestringCustom field type. One of: Text, Number, Money, Date, Datetime, SingleSelect, Boolean, Url.
DefaultValuemixedCustom field default value. Content depends on field type. Optional. *
DescriptionstringText description of custom field. Optional.
VisiblebooleanTrue, if custom field is visible to subscribers in e.g. Preference Center.
RequiredbooleanTrue, if custom field is required when subscribing to a list.
Optionsarray[complex]Array of options for single select field.

MultiData part of request for creating new custom fields.

MultiData element children:

Element/attributeTypeNotes
Fieldsarray[complex]Array of Field elements.

Field element children: 

Element/attributeTypeNotes
NamestringCustom field name.
FriendlyNamestringCustom field “friendly” name for display purposes.
TypestringCustom field type. One of: Text, Number, Money, Date, Datetime, SingleSelect, Boolean, Url.
DefaultValuemixedCustom field default value. Content depends on field type. Optional. *
DescriptionstringText description of custom field. Optional.
VisiblebooleanTrue, if custom field is visible to subscribers in e.g. Preference Center.
RequiredbooleanTrue, if custom field is required when subscribing to a list.
Optionsarray[complex]Array of options for single select field.

Option element children:

Element/attributeTypeNotes
FriendlyNamestringCustom field “friendly” name for display purposes.
ValuestringCustom 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 typeAllowed xsi:typeExample values
Textxsd:stringthis is a test, foobar
Numberxsd:integer12345
Moneyxsd:decimal, xsd:integer123.45, 123
Datexsd:date1985-03-12 **
Datetimexsd:dateTime, xsd:date1985-03-12T12:00:00
Booleanxsd:booleantrue, false, 1, 0
Urlxsd:stringhttp://www.domain.com/page.html
SingleSelectxsd:stringvalue1, 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/attributeTypeNotes
NamestringName of added custom field.
IdintID of added custom field.

Response MultiData element:

Element/attributeTypeNotes
Dataarray[complex]Array of field data elements.

Field data element children:

Element/attributeTypeNotes
NamestringName of added custom field.
IdintID 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>