Jump to content

AddSubscriberWithCustomFields()

Adds a new subscriber, with custom field data, to a contact list. To add a subscriber without custom field data, use the AddSubscriber method.

Parameters

ApiKey (Required)
    Your application authentication key. Click here to find out more.

ListID (Required)
    The ID number of the list to which the subscriber should be added. Click here to find out more.

Email (Required)
    The email address of the subscriber you would like to add.

Custom Fields (Required)
    An array of custom field data associated with the destination list. Note: custom fields not specified will be left blank in the new subscriber's record.  For each custom field, specify this information:

  • Field ID - the ID number of the custom field; you can get custom field information, including the ID, via the GetListDetails method
  • Value - the field value to assign to this subscriber.  See the Usage Notes section for important requirements related to specifying field data.
    Click here for important information about the manipulation of custom field value with the API.

Return Value

On success, this method returns a "success" response (code 0). On failure, a SOAP fault exception is thrown with one of the fault codes below.

Usage Notes

While you need not provide all custom fields, you must provide at least those that are required; all others that are either left out, or specified with blank values, will be left blank in the new subscriber's record.

For most field types, specifying basic string data will suffice.  But please note the following requirements for specifying data of certain special field types:
    Checkbox (i.e. multi-select) fields - provide mutiple values, each within double quotes, and separated by commas; the data is returned in this same format via GetSubscriber (this is a change from version 1 of the API, where data had to be provided in a cumbersome format)
    Date fields - dates must be provided in YYYY-MM-DD format

For "pick list" (dropdown) fields, we strongly recommend you specify only values that are contained in the current list of field values. eConnect Email does allow users to change the list of dropdown choices, including renaming, adding, and deleting them. Because of this, eConnect Email will accept current item choices, as well as the original list choices, as long as those original values were retained and simply renamed. In the end, we strongly recommend you keep any code up-to-date with the current list of the field choices.

Fault Codes

1 - Invalid Email Address
    The email value is malformed or invalid
2 - Subscriber Already Exists
    The email already exists in the specified list
20 - Invalid ListID
    The Associated List is not valid
100 - Invalid API Key
    The API key is not valid or expired
300 - Invalid custom field(s) ([ID=FIELD_ID Value="FIELD_VALUE"], [...])
    The supplied custom field data is invalid, or the field(s) do not exist
400 - Missing Required Custom Field(s) ([ID=FIELD_ID Name="FIELD_NAME", [...])
    The listed custom fields are required but were not specified with data

SOAP Sample Request


    
    
        
            
                STRING
                INT
                STRING
                
                    <item>
                        <FieldID>INT</FieldID>
                        <Value>STRING</Value>
                    </item>
                    <item> ... </item>

SOAP Sample Response


    
    
        
            
                INT
                STRING

PHP Example

// Import the eConnect Email API Toolkit
require_once('eConnectEmail_API_Toolkit.php');

$eConnectEmailApi = TheKeyMakerClient('YOUR_API_KEY');

$CustomFields = array('CUSTOM_FIELD_ID' => 'CUSTOM_FIELD_VALUE',
                      'CUSTOM_FIELD_ID' => 'CUSTOM_FIELD_VALUE',
                      'CUSTOM_FIELD_ID' => 'CUSTOM_FIELD_VALUE');

$result = $eConnectEmailApi->AddSubscriberWithCustomFields(LIST_ID, 
                                                          'EMAIL_ADDRESS',
                                                          $CustomFields);

// Show the results
print 'Response: <pre>';
print_r($result);
print '</pre>';

Code Sample - ASP.NET C#

TheKeyMaker_v20 api= new TheKeyMaker_v20();
string apiKey = "YOUR_API_KEY";
int ListID = LIST_ID;
string Email = "EMAIL_ADDRESS";
string RetVal = "";
string CustomField1 = CUSTOM_FIELD_ID;
string CustomField1Value = CUSTOM_FIELD_VALUE;
string CustomField2 = CUSTOM_FIELD_ID;
string CustomField2Value = CUSTOM_FIELD_VALUE;
string CustomField3 = CUSTOM_FIELD_ID;
string CustomField3Value = CUSTOM_FIELD_VALUE;
try
{
    // Set up input parameters
    AddSubscriberWithCustomFieldsParams addsubCParams = new AddSubscriberWithCustomFieldsParams();
    addsubCParams.ApiKey = apiKey;
    addsubCParams.ListID = ListID;
    addsubCParams.Email = Email;
    
    // Set up custom fields
    List<CustomFieldsParams> customFields = new List<CustomFieldsParams>();
    customFields.Add(AddCustomFieldParam(CustomField1, CustomField1Value));
    customFields.Add(AddCustomFieldParam(CustomField2, CustomField2Value));
    customFields.Add(AddCustomFieldParam(CustomField3, CustomField3Value));
    addsubCParams.CustomFields = customFields.ToArray();

    // Invoke method and store result
    CodeReturnValues addsubCReturn = api.AddSubscriberWithCustomFields(addsubCParams);

    // Display results
    RetVal = FormatValue("Code", addsubCReturn.Code.ToString())
        + FormatValue("Response", addsubCReturn.Response);
}
catch (Exception ex)
{
    RetVal = "ERROR: " + ex.Message + "

" + ex.StackTrace;
}