Modify Subscriber With Custom Fields 2.0

ModifySubscriberWithCustomFields()

Modify a subscribers email address including their custom field data

Parameters

ApiKey (Required)
    Your application authentication key. Click here to find out more.
ListID (Required)
    The list you would like to add the subscriber to. Click here to find out more.
Email (Required)
    The email address of the subscriber you would like to modify.
NewEmail (Required)
    The new email address. (If you would not like to change the email address pass the current email address here.)
Confirmed (Required)
    Allows you to change the confirmed status of the subscriber. (1 for confirmed, 0 for unconfirmed)
Status (Required)
    The status of the subscriber. Acceptable values: 'active', 'bounced', 'unsubscribed', ''(If you pass it an empty string no change will occur.). Click here to find out more.

Custom Fields (Required)
An array of custom field data associated with the destination list. Note: custom fields not specified will retain their values, and any required custom fields provided must have values. 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
3 - Subscriber Does Not Exist
    The email does not exist in the specified list
4 - Invalid New Email Address
    The new email value is malformed or invalid
5 - A subscriber already exists with the new email address
    The new email address you provided is already in use by another subscriber on that 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) ([FIELD_ID] Value="FIELD_VALUE", ...)
    The supplied custom fields are invalid or do not exist
500 - The Email Address Could Not Be Changed
    The new email address could not be applied due to api communications
600 - The subscriber could not be updated
    An error occurred when attempting to submit the status modifications.

SOAP Sample Request


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

SOAP Sample Response

Code Sample - PHP

// 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');

// Status accepts: active, bounced, unsubscribed or 
// an empty string to prevent change.
$result = $eConnectEmailApi->ModifySubscriberWithCustomFields(LIST_ID, 
                                      'EMAIL_ADDRESS', 'NEW_EMAIL', 
                                      CONFIRMED, 'STATUS', $CustomFields);

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

Code Sample - ASP.NET C#

            TheKeyMaker_v20 api = new TheKeyMaker_v20();
            // Set up input parameters
            ModifySubscriberWithCustomFieldsParams modifysubCParams = new ModifySubscriberWithCustomFieldsParams();
            modifysubCParams.ApiKey = txtApiKey.Text;
            modifysubCParams.ListID = int.Parse(txtModifySubCListID.Text);
            modifysubCParams.Email = txtModifySubCEmail.Text;
            modifysubCParams.NewEmail = txtModifySubCNewEmail.Text;
            modifysubCParams.Confirmed = chkModifySubCConfirmed.Checked ? 1 : 0;
            modifysubCParams.Status = txtModifySubCStatus.Text;
            // Send only custom field values that are specified

            List customFields = new List();
            if (txtModifySubCFieldID1.Text.Trim() != "")
                customFields.Add(AddCustomFieldParam(txtModifySubCFieldID1.Text.Trim(), txtModifySubCValue1.Text.Trim()));
            if (txtModifySubCFieldID2.Text.Trim() != "")
                customFields.Add(AddCustomFieldParam(txtModifySubCFieldID2.Text.Trim(), txtModifySubCValue2.Text.Trim()));
            if (txtModifySubCFieldID3.Text.Trim() != "")
                customFields.Add(AddCustomFieldParam(txtModifySubCFieldID3.Text.Trim(), txtModifySubCValue3.Text.Trim()));
            if (txtModifySubCFieldID4.Text.Trim() != "")
                customFields.Add(AddCustomFieldParam(txtModifySubCFieldID4.Text.Trim(), txtModifySubCValue4.Text.Trim()));
            if (txtModifySubCFieldID5.Text.Trim() != "")
                customFields.Add(AddCustomFieldParam(txtModifySubCFieldID5.Text.Trim(), txtModifySubCValue5.Text.Trim()));
            modifysubCParams.CustomFields = customFields.ToArray();

            // Invoke method and store result
            CodeReturnValues modifysubCReturn = api.ModifySubscriberWithCustomFields(modifysubCParams);

            // Display results
            lblResult.Text = FormatValue("Code", modifysubCReturn.Code.ToString())
                + FormatValue("Response", modifysubCReturn.Response);

api.eConnectEmail.com
Interacting with the eConnect Email's API