Skip to content

Custom Fields

Create a New Custom Field

POST /api.php

This endpoint is used to create a new custom field for a subscriber list. It allows for various field types and configurations, including preset fields, validation rules, and merge tag aliases.

Request Body Parameters:

ParameterDescriptionRequired?
SessionIDThe ID of the user's current sessionYes
APIKeyThe user's API key. Either SessionID or APIKey must be provided.Yes
CommandCustomField.CreateYes
SubscriberListIDThe ID of the subscriber list to which the custom field will be addedYes
FieldNameThe name of the custom fieldConditional
FieldTypeThe type of the custom field (e.g., 'Date field', 'Drop down', etc.)Conditional
DefaultValueThe default value for the custom fieldNo
ValidationMethodThe method used to validate the field (e.g., 'None', 'Custom')No
ValidationRuleThe rule used for custom validationConditional
MergeTagAliasAn alias for the merge tag associated with the custom fieldNo
PresetNameThe name of the preset to use for the custom fieldConditional
YearsThe range of years for a 'Date field' typeConditional
OptionLabelThe labels for the options of the fieldConditional
OptionValueThe values for the options of the fieldConditional
OptionSelectedThe selected options of the fieldConditional
IsRequiredWhether the field is required ('Yes' or 'No')No
IsUniqueWhether the field must have a unique value ('Yes' or 'No')No
VisibilityThe visibility of the field ('Public' or 'User Only')No
IsGlobalWhether the field is global ('Yes' or 'No')No
bash
curl -X POST https://example.com/api.php \
  -d 'SessionID=exampleSessionId' \
  -d 'APIKey=exampleApiKey' \
  -d 'Command=CustomField.Create' \
  -d 'SubscriberListID=123' \
  -d 'FieldName=Birthdate' \
  -d 'FieldType=Date field' \
  -d 'DefaultValue=1990-01-01' \
  -d 'ValidationMethod=Custom' \
  -d 'ValidationRule=after:1980-01-01' \
  -d 'MergeTagAlias=birthday' \
  -d 'IsRequired=Yes' \
  -d 'IsUnique=No' \
  -d 'Visibility=Public' \
  -d 'IsGlobal=No'
json
{
  "Success": true,
  "ErrorCode": 0,
  "ErrorText": "",
  "CustomFieldID": 456
}
json
{
  "Success": false,
  "ErrorCode": [1],
  "ErrorText": "Missing subscriber list id"
}
txt
1: Missing subscriber list id
2: Missing field name
3: Missing field type
4: Missing validation rule
5: Invalid preset name
1000: Merge tag alias code has been set for another custom field
1001: Merge tag alias code includes invalid characters

Update Custom Field

POST /api.php

This endpoint is used to update the details of an existing custom field in the system.

Request Body Parameters:

ParameterDescriptionRequired?
SessionIDThe ID of the user's current sessionYes
APIKeyThe user's API key. Either SessionID or APIKey must be provided.Yes
CommandCustomField.UpdateYes
CustomFieldIDThe unique identifier for the custom field to be updatedYes
FieldNameThe name of the custom fieldYes
FieldTypeThe type of the custom field (e.g., 'Single line', 'Paragraph text')Yes
SubscriberListIDThe ID of the subscriber list associated with the custom fieldNo
DefaultValueThe default value for the custom fieldNo
MergeTagAliasThe merge tag alias for the custom fieldNo
ValidationMethodThe method used to validate the custom field's valueNo
ValidationRuleThe rule applied for validating the custom field's valueNo
OptionLabelThe label for the field optionNo
OptionValueThe value for the field optionNo
OptionSelectedThe selected option for the fieldNo
VisibilityThe visibility setting for the custom field ('Public' or 'User Only')No
IsGlobalWhether the custom field is global ('Yes' or 'No')No
IsRequiredWhether the custom field is required ('Yes' or 'No')No
IsUniqueWhether the custom field is unique ('Yes' or 'No')No
YearsThe years option for a date fieldNo
bash
curl -X POST https://example.com/api.php \
-H "Content-Type: application/json" \
-d '{
    "SessionID": "your-session-id",
    "APIKey": "your-api-key",
    "Command": "CustomField.Update",
    "CustomFieldID": "123",
    "FieldName": "New Field Name",
    "FieldType": "Single line"
}'
json
{
    "Success": true,
    "ErrorCode": 0,
    "ErrorText": ""
}
json
{
    "Success": false,
    "ErrorCode": [1],
    "ErrorText": ["Missing custom field id"]
}
txt
1: Missing custom field id
2: Missing field name
3: Missing field type
4: Missing validation rule
6: Invalid custom field id
7: Invalid field type
8: Invalid validation method
9: Invalid visibility value
10: Invalid IsRequired value
11: Invalid IsUnique value
12: Invalid IsGlobal value
1000: Merge tag alias code has been set for another custom field
1001: Merge tag alias code includes invalid characters.

Delete Custom Fields

POST /api.php

This endpoint is used to delete one or more custom fields associated with a user. The custom fields to be deleted are specified by their IDs.

Request Body Parameters:

ParameterDescriptionRequired?
SessionIDThe ID of the user's current sessionYes
APIKeyThe user's API key. Either SessionID or APIKey must be provided.Yes
CommandCustomFields.DeleteYes
CustomFieldsA comma-separated list of custom field IDs to deleteYes
bash
curl -X POST https://example.com/api.php \
-H "Content-Type: application/json" \
-d '{
    "SessionID": "your-session-id",
    "APIKey": "your-api-key",
    "Command": "CustomFields.Delete",
    "CustomFields": "1,2,3"
}'
json
{
  "Success": true,
  "ErrorCode": 0,
  "ErrorText": ""
}
json
{
  "Success": false,
  "ErrorCode": {
    "customfields": 1
  },
  "ErrorText": ["Custom field ids are missing"]
}
txt
1: Custom field ids are missing

Retrieve Custom Fields

POST /api.php

This endpoint retrieves custom fields associated with a specific subscriber list. It allows for the optional return of global custom fields as well.

Request Body Parameters:

ParameterDescriptionRequired?
SessionIDThe ID of the user's current sessionYes
APIKeyThe user's API key. Either SessionID or APIKey must be provided.Yes
CommandCustomFields.GetYes
SubscriberListIDThe unique identifier for the subscriber listYes
ReturnGlobalCustomFieldsA boolean value to specify if global custom fields should be returnedNo
OrderFieldThe field by which to order the custom fieldsNo
OrderTypeThe order type, either 'ASC' for ascending or 'DESC' for descendingNo
bash
curl -X POST https://yourdomain.com/api.php \
-H "Content-Type: application/json" \
-d '{
    "SessionID": "your-session-id",
    "APIKey": "your-api-key",
    "Command": "CustomFields.Get",
    "SubscriberListID": "123",
    "ReturnGlobalCustomFields": true,
    "OrderField": "FieldName",
    "OrderType": "ASC"
}'
json
{
    "Success": true,
    "ErrorCode": 0,
    "ErrorText": "",
    "TotalFieldCount": 5,
    "CustomFields": [
        {
            "FieldID": "1",
            "FieldName": "CustomField1",
            "FieldType": "text",
            // Additional custom field details...
        },
        // Additional custom fields...
    ]
}
json
{
    "Success": false,
    "ErrorCode": 1,
    "ErrorText": "Missing subscriber list id"
}
txt
1: Missing subscriber list id

Any questions? Contact us.