The Save command requires the following arguments: Command and Data.
cmd=save&data=email,first,last,custom_user_id,custom_favorite^jayne.doe@domain.com,Jayne,Doe,112,blue
The command is ‘save' and the contact with email 'jayne.doe@domain.com' will be created.
The Save command expects as least one field in the Data argument. The email address of the contact is always required in order to create a contact record. If the contact does not yet exist, a Contact record will be created using the email address and first name as the primary key. If the contact does exist, the Contact record will be updated with any data defined in additional Data fields. If allow_duplicates is defined in the header and the first name is different from an existing contact, a new contact will be created.
To clear a data field, you must be using version 8.8.0 or newer. If a field is left blank in the command, it will be ignored. You can clear a data field by sending the string 'NULL'. For example:
cmd=save&data=email,first,last,custom_user_id,custom_favorite^jayne.doe@domain.com,Jayne,Doe,112,NULL
You can change one or many contacts with the same Save 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.
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):
cmd=save&realm=myrealm_child&data=email,first,last,custom_id,format_number ^*jane@domain.com,Jane,Doe,112,1 ^*jane@domain.com,JD,Doe,114,1 ^john@domain.com,John,Smith,1738,1
Three contact records will be created or updated in the realm ‘myrealm_child’, a child of the Realm defined in the header. If a record for the contact with the same email address and first name already exists, then the record will be updated. If the record does not exist, then a new record will be created with the first name, ‘Jane’, last name, ‘Doe’, and custom field “id” set to ‘112’.
Customer Key Example
Some systems have the ability to define a unique Customer Key per contact. If your realm has Customer Key enabled, then you must include the customer_key in the data argument along with email. For example:
cmd=save&realm=myrealm_child&data=customer_key,email,first,last,custom_id,format_number ^11293,jane@domain.com,Jane,Doe,112,1
If the Customer Key is not included, the command will fail.
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:
cmd=sub&realm=myrealm&list_id=55&format=99&data=email,first,last,custom_gender,publishing_flight_id^jane@domain.com,Jane,Doe,female,25
Errors
A Save command will fail if multiple contacts with the same email exist. Since Contact records are allowed to have the same Email address as long as the First Name is unique, you may wish to include the first name in your Subscribe command to avoid encountering errors or updating the wrong Contact.
Arguments
The Save command supports the following arguments:
|
Name |
Req? |
Description |
Argument |
|
Command |
Yes |
Defines the command to use. |
cmd=save |
|
Realm |
|
Name of the realm to run the command. This is optional, and only necessary when submitting files to a parent realm to manipulate data for a child realm |
realm=[realm_name] |
| Data | Yes | Contact related data. Email is always required, and additional fields are optional. |
data=[fields] |
*Publishing Flight added in v16.16