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] |
Comments