API: HTTP Update Contact

The Update command allows you to change data, except email, for an existing Contact. 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 contact 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 contact is always required to edit a Contact record. If the Contact does not exist, no update will occur. If the Contact does exist, the Contact record will be updated with any data defined in the Data fields.

The Identity field must contain unique data for each contact. It should be a custom field with data unique to each contact, for example an Account ID (custom_account_id) or Customer ID (custom_customer_id). If there are multiple contacts with the same data in the Identity field, then the oldest contact 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 contacts with the same Email if each has a different First Name.

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

To update the contact 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 contact records will be updated based on the 'custom_id' Identity field. The first and last names will be updated, and the contact 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 contact. 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 contact 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 contact 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

Publishing Flight Example

Some Realms have the ability to deploy campaigns to contacts in a specified order, called the Publishing Flight ID. If your realm has Publishing Flight enabled, then you can include the publishing_flight_id in the data argument along with email. For example:

api_web?r=myrealm&p=mypass&c=update&list_id=5&format=99&force_sub=1&data=email,first,last,custom_gender,publishing_flight_id^jane@domain.com,Jane,Doe,female,25

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 contacts 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 contact, 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 contact to be updated. The Identity field must contain unique data for each contact.	identity_field=[custom_field_name]
Data	Yes	Contact related data. Email is always required, and additional fields are optional.	data=[fields] d=[fields]