Update Subscriber

The Update command allows you to change data, except email, for an existing Subscriber. The Update command requires the following arguments: Command, Realm, Password, Identity Field, List, and Data.

api_web?r=myrealm&p=mypass&c=update&list_id=5&identity_field=custom_user_id&data=email,first,last,custom_user_id^jane@domain.com,Jayne,Doe,112

The command is ‘update', the realm is ‘myrealm’ and the password is ‘mypass’.  The unique field used to look up the subscriber record is the Identity field 'custom_user_id' with a value of '112' and email 'jane@domain.com' .  The first name and last name fields updated.

The Update command expects as least one field in the Data argument.  The email address of the subscriber is always required to edit a Subscriber record.  If the Subscriber does not exist, no update will occur.  If the Subscriber does exist, the Subscriber record will be updated with any data defined in the Data fields.

The Identity field must contain unique data for each subscriber.  It should be a custom field with data unique to each subscriber, for example an Account ID (custom_account_id) or Customer ID (custom_customer_id).  If there are multiple subscribers with the same data in the Identity field, then the oldest subscriber will be updated and the others will be ignored.  For this reason, you should not use the Email as the Identity field since it is possible to have multiple subscribers with the same Email if each has a different First Name.

You can change one or many subscribers with the same Update command.  To update multiple Subscriber records, include additional subscribers separated by the carat (^) character.  Each additional subscriber must have the same number of data fields defined, and data for the identity field.

To update the subscriber selected format, use format_number or format_text in the Data field definition.

Example

Using all commands and arguments (please note the command is wrapped for display purposes only):

api_web?r=myrealm&p=mypass&c=update&list_id=5&identity_field=custom_id&data=email,first,last,custom_id,format_number^*jane@domain.com,Jayne,Doe-Smith,112,1^*jane@domain.com,JD,Doe,114,1^john@domain.com,John,Smith,1738,1

Three subscriber records will be updated based on the 'custom_id' Identity field.  The first and last names will be updated, and the subscriber selected email format will be set to '1' for plain-text.

Successful results return:

SUCCESS: 3 record(s) procesed. 3 users updated.  

Customer Key Example

Some systems have the ability to define a unique Customer Key per subscriber.  If your realm has Customer Key enabled, then the Update command is not supported and will fail in releases prior to 9.2.0.  To update a subscriber email address in versions prior to 9.2.0, use the Change command instead.

In releases 9.2.0 and newer, you can use the Update command to create a new subsriber record or update an existing subscriber record.  To do this, use the Customer Key field as the Identity Fields, for example:

api_web?r=myrealm&p=mypass&c=update&list_id=5&identity_field=customer_key&data=customer_key,email,first,last^00123,jane@domain.com,Jane%20Marie,Doe-Smith

Results

The Update command outputs either a SUCCESS or FAILURE message. 

Success

The Update command success message returns the SUCCESS message and includes the number of records processed and subscribers updated.  The result format is:

SUCCESS: [number_a] record(s) processed. [number_b] user updated.

If the Update command includes records for more than one subscriber, it is possible that not all records will be updated.  The result only indicates the total number of updates and does not return errors or reasons why some may have failed.

Failure

A Update command will fail for several reasons.  The result format is:

FAILURE: [Reason]  

Arguments

The Update command supports the following arguments:

Name	Req?	Description	Argument
Command	Yes	Defines the command to use.	cmd=update c=update
Realm	Yes	Name of the realm to run the command.  This is required, and the command will fail if the realm and password do not match.	realm=[realm_name] r=[realm_name]
Password	Yes	Authentication code for API access.  This is required, and the command will fail if the realm and password do not match.	pwd=[password] p=[password]
List ID	Yes	Identifier of the list to apply the command.	list_id=[list_id]
Identity Field	Yes	Specifies which field to use to lookup the subscriber to be updated.  The Identity field must contain unique data for each subscriber.	identity_field=[custom_field_name]
Data	Yes	Subscriber related data.  Email is always required, and additional fields are optional.	data=[fields] d=[fields]