Follow

Update Subscriber

The Update command allows you to change data, except email, for an existing Subscriber.

Arguments

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.  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.

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.

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]

 

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]  

 
Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments

Powered by Zendesk