Import to a Database

ImportList

This interface allows importing a batch file containing new, modified, or opted out contacts. Contacts can also be added to an existing Contact List.

Use the steps below to perform an import through the API:

  1. Upload the source file to the Watson Campaign Automation SFTP server.
  2. Upload the Definition and Column Mapping file to the Watson Campaign Automation SFTP server.
  3. Authenticate the user with a Login API call.
  4. Initiate the database import using an ImportList call.
  5. Determine status of the background import job by making a GetJobStatus API call (optional).
  6. Log off from the Watson Campaign Automation API using a Logout API call.

You must place all files in the upload directory on the FTP server or the database import service will not “find” them.

Note: To learn more about setting up an SFTP account, click here.

Below is the syntax of the request and response:

Operation <ImportList>     
Elements  MAP_FILE  The name of the Mapping file in the upload directory of the FTP server to use for the import.   
  SOURCE_FILE The name of the file containing the contact information to use in the import. This file must reside in the upload directory of the FTP Server.   
  FILE_ENCODING  Optional 

Defines the encoding of the source file. Supported values are:

UTF‐8

ISO‐8859‐1

If not specified, Watson Campaign Automation will use the Organization default encoding. 

Example 
<soapenv:Envelope xmlns:
soapenv=”http://schemas.xmlsoap.org/soap/envelope/” xmlns:ses=”SilverpopApi:EngageService.SessionHeader” xmlns:user=”SilverpopApi:EngageService.ListMgmt.UserActions”> <soapenv:Header> <ses:sessionHeader> <ses:sessionid>50F4F411A048A4DDA159ABE2954E4610</ses:sessionid> </ses:sessionHeader> </soapenv:Header> <soapenv:Body> <user:ImportList> <user:MAP_FILE>List_Import_Test.xml</user:MAP_FILE> <user:SOURCE_FILE>List_Import_Test.csv</user:SOURCE_FILE> </user:ImportList> </soapenv:Body> </soapenv:Envelope>
Response  <RESULT>     
Elements  SUCCESS TRUE if successful.   
  JOB_ID  Identifies the Watson Campaign Automation Background Job created and scheduled for this import.   
Example
<envelope:Envelope 
xmlns=”SilverpopApi:EngageService.ListMgmt.UserActions” xmlns:envelope=”http://schemas.xmlsoap.org/soap/envelope/”> <envelope:Header/> <envelope:Body> <RESULT> <SUCCESS>TRUE</SUCCESS> <JOB_ID>502732</JOB_ID> </RESULT> </envelope:Body> </envelope:Envelope>

  

Database Definition and Column Mapping Format

Mapping is the process of associating columns in the import file with the corresponding fields in the database. For example, Column 1 in the mapping file corresponds to Name in the database. You must describe the details
of the database including its columns as well as the format of the source file (which contains the actual contact records). You will place this information in an XML mapping file and upload it to a specified directory on an FTP server.

Add the <KEY_COLUMN> element (set to True) in a field declaration in the mapping file to set a field as a unique key for the database. You can also define more than one unique key field for a database. You must define the EMAIL field in the mapping file and cannot leave it out for an NEK database. The column TYPE should always be set to 9 and the IS_REQUIRED element should always be set to True. However, you must specify KEY_COLUMN as True in order to list it as a unique key. If not specified, it will be a regular field in the database.

Watson Campaign Automation returns errors in the submission as part of the response. However, Watson Campaign Automation does not detect errors in the mapping file or the source file until it runs the data job. You can view Data Job errors on the Data Jobs screen of the Watson Campaign Automation user interface.

The XML file contains four main sections:

  1. LIST_INFO: defines information about the database you are creating (or updating), as well as actions to perform on this database.
  2. COLUMNS: if creating a new database, this section consists of one or more COLUMN elements. Each COLUMN element contains child elements to define the attributes for that column (for example, name,
    type, and key column). If the action is not CREATE (and you are not adding new columns to the database), you can exclude the COLUMNS section from the mapping file.
  3. MAPPING: this section also consists of COLUMN elements. Each COLUMN element contains child elements to define the attributes for mapping that column (for example, name and index).
  4. CONTACT_LISTS: this optional section is used to specify one or more Contact Lists that all contacts will be added to in addition to the database. This section may be used with all actions except OPT_OUT.

The Import Data Job will handle imports of contacts to a database having No Unique Identifier as follows:

  • If the ACTION is CREATE or ADD_ONLY and SYNC_FIELDS are NOT specified, each row in the source file will result in a new contact.
  • If the ACTION is CREATE and SYNC_FIELDS are specified, rows having identical SYNC_FIELDS within the source file will be rejected as duplicates.
  • If the ACTION is ADD_ONLY and SYNC_FIELDS are specified, rows having identical SYNC_FIELDS within the source file or in the database will be rejected as duplicates.
  • If the ACTION is UPDATE_ONLY, contacts matching the SYNC_FIELDS will be updated; all other contacts will be ignored. If more than one contact is found matching the lookup columns, all contacts will be updated.
  • If the ACTION is ADD_AND_UPDATE, contacts matching the SYNC_FIELDS will be updated; all other contacts will be added. If more than one contact is found matching the lookup columns, all contacts will be updated.
  • If the ACTION is OPT_OUT, contacts matching the SYNC_FIELDS will be opted out; all other contacts will be ignored. If more than one contact is found matching the lookup columns, the all matching contacts will be opted out.

Note: All column names are case‐sensitive, meaning you must ensure the names in the mapping file and source file exactly match the field names in the Watson Campaign Automation database.

The table below defines the sections. You should contain each of these sections within the LIST_IMPORT element:

Section <LIST_INFO> The LIST_INFO section defines the structure of the database you are creating or updating, as well as the action to perform on this database. 
Elements  ACTION

Defines the type of import you are performing. The following is a list of valid values and how Watson Campaign Automation interprets them:

CREATE – create a new database.

ADD_ONLY – only add new contacts to the database. Ignore existing contacts when found in the source file.

UPDATE_ONLY – only update the existing contacts in the database. Ignore contacts who exist in the source file but not in the database.

ADD_AND_UPDATE – process all contacts in the source file. If they already exist in the database, update their values. If they do not exist, create a new record in the database for the contact.

OPT_OUT – opt out any contact in the source file who is already in the database. Ignore contacts who exist in the source file but not the database. 

  LIST_TYPE

Defines the type of database. Only specified if the ACTION is CREATE. Supported values are:

0 – Database

6 – Seed list

13 – Suppression list

  LIST_NAME Defines the name of the new database if the ACTION is CREATE (names must be unique). 
  LIST_ID Unique ID of the database in the Watson Campaign Automation system. You must provide this for all ACTION values (except CREATE).
  LIST_VISIBILITY

Required. Defines the visibility of the newly created database.

0 – private

1 – shared

  PARENT_FOLDER_PATH Used with the CREATE ACTION to specify the folder to place the new database in. Use the VISIBILITY element to specify Private/Shared.
  FILE_TYPE

Defines the formatting of the source file. Supported values are:

0 – CSV file

1 – Tab‐separated file

2 – Pipe‐separated file 

  HASHEADERS The HASHEADERS element is set to true if the first line in the source file contains column definitions. 
  LIST_DATE_FORMAT Optional

Used to specify the date format and date fields in your file if your date format differs from “mm/dd/yyyy” (the month, day, and year can be in any order you choose).

Valid values for Month are:

mm (e.g. 01)
m (e.g. 1)
mon (e.g. Jan)
month (e.g. January)

Valid values for Day are:

dd (e.g. 02)
d (e.g. 2)

Valid values for Year are:

yyyy (e.g. 1999)
yy (e.g. 99)

Separators may be up to two characters in length and can consist of periods, commas, question marks, spaces, and forward slashes (/). 

Examples:

For “Jan 2, 1975” your LIST_DATE_FORMAT would be “mon d, yyyy”

For “1975/09/02” your LIST_DATE_FORMAT would be “yyyy/mm/dd”

  DOUBLE_OPT_IN Optional

If this element accompanies the CREATE action, Watson Campaign Automation creates a Double Opt‐In database. If you do not specify the element, the Organization default is used.

Note: The database security settings that allow you to use the database import operation are, by default, disabled for all Double Opt‐In databases.

  ENCODED_AS_MD5 Optional If this element is set to true, email addresses in the Email column will be MD5 encoded.
  SYNC_FIELDS Optional

Required if the database has no Unique Identifier and action is UPDATE_ONLY, ADD_AND_UPDATE, or OPT_OUT. Used to specify what columns are used to look up a contact in a database that has no Unique Identifier defined. Include a SYNC_FIELD element for each database column that defines a unique contact.

Note: If more than one contact is found matching the lookup columns, all matching contacts will be updated. If the ACTION is opt out, all matching contacts will be opted out. 

  Child Element SYNC_FIELD XML nodes defining the column Name of the unique identifier fields. 
    Child Element NAME Defines the field name.
Section <COLUMNS> This section defines how many columns to write to the database (0 or more). Use aseparate COLUMN element to define each database column. If the ACTION is not CREATE and you are not adding new columns to the database, you can exclude the COLUMNS section from the mapping file. 
Elements COLUMN
  Child Elements NAME Defines the name of the column.
    TYPE

Defines what type of column to create. The following is a list of valid values:

0 – Text column

1 – YES/No column

2 – Numeric column

3 – Date column

4 – Time column

5 – Country column

6 – Select one

8 – Segmenting

9 – System (used for defining EMAIL field only)

17 – Timestamp

20 – Multi‐Select

Note: The import process does not validate the data in the source file against these column types.

    IS_REQUIRED

Defines whether to create the column as “required” when contacts are providing information through a Web form. Valid values are True and False.

Note: The import process does not use this information to validate the data. 

    KEY_COLUMN Added to field definition and defines a field as a unique key for the database when set to True. You can define more than one unique field for each database. 
    DEFAULT_VALUE Defines the default value of the column used by the Send process if the contact does not contain a value for this column.
    SELECTION_VALUE Defines values in a drop‐down list. You must provide at least one element for each value. Used in conjunction with TYPE 6. 
Section <MAPPING>

Use the MAPPING section to define which columns in the source file map to which columns in the database.

Define each column in its own COLUMN element.

Elements COLUMN
  Child Elements INDEX The INDEX element defines the order in which the source file defines this column.
    NAME

The name of the database column to which Watson Campaign Automation maps the source file column. You can use the following system‐defined names in the mapping file:

EMAIL – the email address.

EMAIL_TYPE – the type of contact body to send.

CREATED_FROM – An integer defining where Watson Campaign Automation collected the contact’s information.

OPTED_IN – the date and time the contact was opted into the database. Watson Campaign Automation assumes all times to be GMT. If there is no optin date specified, the system will insert the current date and time (in GMT).

OPT_IN_DETAILS – any information (up to 250 characters) that defines where

The name of the database column to which Watson Campaign Automation maps the source file column. You can use the following system‐defined names in the mapping file:

EMAIL – the email address.

EMAIL_TYPE – the type of contact body to send.

CREATED_FROM – An integer defining where Watson Campaign Automation collected the contact’s information.

OPTED_IN – the date and time the contact was opted into the
database. Watson Campaign Automation assumes all times to be GMT. If there is no optin date specified, the system will insert the current date and time (in GMT).

OPT_IN_DETAILS – any information (up to 250 characters) that defines where Watson Campaign Automation obtained the contact’s information.

OPTED_OUT – the date and time the contact opted out of the database (for OPT_OUT actions only).

All system‐type field names must be in uppercase.

    INCLUDE

Defines whether to include the element in the database import.

You do not need to include all source file columns in the import.

This element allows you to specify which columns to skip during the Import process. Valid values are True and False

Section <CONTACT LISTS> Use the CONTACT_LISTS section if you want to specify one or more Contact Lists that all contacts will be added to in addition to the database. This section may be used with all actions except OPT_OUT.
  Child Elements CONTACT_LIST_ID Zero to many elements defining the Id of an existing Contact List.

 

Example Mapping Files

Example 1 

This example shows a simple mapping file with the unique key set as CustID. Email is not a unique key in this example. 

<LIST_IMPORT>
  <LIST_INFO>
    <ACTION>CREATE</ACTION>
    <LIST_NAME>Premier Accts</LIST_NAME>
    <LIST_VISIBILITY>0</LIST_VISIBILITY>
    <FILE_TYPE>0</FILE_TYPE>
    <HASHEADERS>true</HASHEADERS>
  </LIST_INFO>
  <COLUMNS>
    <COLUMN>
      <NAME>EMAIL</NAME>
      <TYPE>9</TYPE>
      <IS_REQUIRED>true</IS_REQUIRED>
    </COLUMN>
    <COLUMN>
      <NAME>CustID</NAME>
      <TYPE>0</TYPE>
      <IS_REQUIRED>true</IS_REQUIRED>
      <KEY_COLUMN>true</KEY_COLUMN>
    </COLUMN>
  </COLUMNS>
  <MAPPING>
    <COLUMN>
      <INDEX>1</INDEX>
      <NAME>EMAIL</NAME>
      <INCLUDE>true</INCLUDE>
    </COLUMN>
    <COLUMN>
      <INDEX>2</INDEX>
      <NAME>CustID</NAME>
      <INCLUDE>true</INCLUDE>
    </COLUMN>
  </MAPPING>
</LIST_IMPORT>

 

Example 2 

This example shows a more complicated mapping file with custom column definitions. Both EMAIL and CustID are unique keys. Contacts are also being added to existing Contact Lists. 

<LIST_IMPORT>
  <LIST_INFO>
    <ACTION>ADD_AND_UPDATE</ACTION>
    <LIST_ID>50194</LIST_ID>
    <FILE_TYPE>0</FILE_TYPE>
    <HASHEADERS>true</HASHEADERS>
  </LIST_INFO>
  <COLUMNS>
    <COLUMN>
      <NAME>EMAIL</NAME>
      <TYPE>9</TYPE>
      <IS_REQUIRED>true</IS_REQUIRED>
      <KEY_COLUMN>true</KEY_COLUMN>
    </COLUMN>
    <COLUMN>
      <NAME>CustID</NAME>
      <TYPE>0</TYPE>
      <IS_REQUIRED>true</IS_REQUIRED>
      <KEY_COLUMN>true</KEY_COLUMN>
    </COLUMN>
    <COLUMN>
      <NAME>Att1</NAME>
      <TYPE>0</TYPE>
      <IS_REQUIRED>false</IS_REQUIRED>
      <DEFAULT_VALUE/>
    </COLUMN>
    <COLUMN>
      <NAME>Att2</NAME>
      <TYPE>0</TYPE>
      <IS_REQUIRED>false</IS_REQUIRED>
      <DEFAULT_VALUE/>
    </COLUMN>
    <COLUMN>
      <NAME>CountryField1</NAME>
      <TYPE>0</TYPE>
      <IS_REQUIRED>false</IS_REQUIRED>
      <DEFAULT_VALUE/>
    </COLUMN>
    <COLUMN>
      <NAME>CountryField2</NAME>
      <TYPE>0</TYPE>
      <IS_REQUIRED>false</IS_REQUIRED>
      <DEFAULT_VALUE/>
    </COLUMN>
    <COLUMN>
      <NAME>DateField1</NAME>
      <TYPE>0</TYPE>
      <IS_REQUIRED>false</IS_REQUIRED>
      <DEFAULT_VALUE/>
    </COLUMN>
  </COLUMNS>
  <MAPPING>
    <COLUMN>
      <INDEX>1</INDEX>
      <NAME>EMAIL</NAME>
      <INCLUDE>true</INCLUDE>
    </COLUMN>
    <COLUMN>
      <INDEX>2</INDEX>
      <NAME>EMAIL_TYPE</NAME>
      <INCLUDE>true</INCLUDE>
    </COLUMN>
    <COLUMN>
      <INDEX>3</INDEX>
      <NAME>CustID</NAME>
      <INCLUDE>true</INCLUDE>
    </COLUMN>
    <COLUMN>
      <INDEX>4</INDEX>
      <NAME>DateField1</NAME>
      <INCLUDE>true</INCLUDE>
    </COLUMN>
  </MAPPING>
  <CONTACT_LISTS>
    <CONTACT_LIST_ID>31279</CONTACT_LIST_ID>
    <CONTACT_LIST_ID>54564</CONTACT_LIST_ID>
  </CONTACT_LISTS>
</LIST_IMPORT>

 

Example 3 

This example shows a mapping file for a database with no unique key where the columns EMAIL and SSN are being used to update contacts. 

<LIST_IMPORT>
  <LIST_INFO>
    <ACTION>UPDATE_ONLY</ACTION>
    <LIST_NAME>Premier Accts</LIST_NAME>
    <LIST_VISIBILITY>0</LIST_VISIBILITY>
    <FILE_TYPE>0</FILE_TYPE>
    <HASHEADERS>true</HASHEADERS>
  </LIST_INFO>
  <SYNC_FIELDS>
    <SYNC_FIELD>
      <NAME>EMAIL</NAME>
    </SYNC_FIELD>
    <SYNC_FIELD>
      <NAME>SSN</NAME>
    </SYNC_FIELD>
  </SYNC_FIELDS>
  <MAPPING>
    <COLUMN>
      <INDEX>1</INDEX>
      <NAME>EMAIL</NAME>
      <INCLUDE>true</INCLUDE>
    </COLUMN>
    <COLUMN>
      <INDEX>2</INDEX>
      <NAME>SSN</NAME>
      <INCLUDE>true</INCLUDE>
    </COLUMN>
    <COLUMN>
      <INDEX>3</INDEX>
      <NAME>First_Name</NAME>
      <INCLUDE>true</INCLUDE>
    </COLUMN>
  </MAPPING>
</LIST_IMPORT>

Export from a Database

ExportList

This interface exports contact data from a database, query, or contact list. Watson Campaign Automation exports the results to a CSV file, then adds that file to the FTP account associated with the current session. You can copy the results file to Stored Files in Watson Campaign Automation.

Note: If the database is a Double Opt‐in database, Watson Campaign Automation only exports confirmed contacts. In addition, the database security settings that allow you to use this operation are, by default, disabled for all Double Opt‐In databases.

Operation <ExportList>  
Elements LIST_ID

Unique identifier for the database, query, or contact list Watson campaign Automation is exporting. 

  EMAIL Optional

If specified, this email address receives notification when the job is complete.

  EXPORT_TYPE

Specifies which contacts to export. Valid values are:

ALL – export entire database.

OPT_IN – export only currently opted‐in contacts.

OPT_OUT – export only currently opted‐out contacts.

UNDELIVERABLE – export only contacts who are currently marked as undeliverable.

 
  EXPORT_FORMAT

Specifies the format (file type) for the exported data. Valid values are:

CSV – create a comma‐separated values file

TAB – create a tab‐separated values file

PIPE – create a pipe‐separated values file 

 
  FILE_ENCODING Optional

Defines the encoding of the exported file. Supported values are:

utf‐8

iso‐8859‐1

If not specified, Watson Campaign Automation uses the Organization default encoding.

  ADD_TO_STORED_FILES Optional

Use the ADD_TO_STORED_FILES parameter to write the output to the Stored Files folder within Watson Campaign Automation.

If you omit the ADD_TO_STORED_FILES parameter, Watson Campaign Automation will move exported files to the download directory of the user’s FTP space.

  DATE_START Optional Specifies the beginning boundary of information to export (relative to the last modified date). If time is included, it must be in 24‐hour format.
  DATE_END Optional Specifies the ending boundary of information to export (relative to the last modified date). If time is included, it must be in 24‐hour format.
Example
<soapenv:Envelope 
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ses="SilverpopApi:EngageService.SessionHeader" xmlns:user="SilverpopApi:EngageService.ListMgmt.UserActions"> <soapenv:Header> <ses:sessionHeader> <ses:sessionid>50F4F411A048A4DDA159ABE2954E4610</ses:sessionid> </ses:sessionHeader> </soapenv:Header> <soapenv:Body> <user:ExportList> <user:LIST_ID>24872</user:LIST_ID> <user:EXPORT_TYPE>ALL</user:EXPORT_TYPE> <user:EXPORT_FORMAT>CSV</user:EXPORT_FORMAT> <user:ADD_TO_STORED_FILES/> <user:DATE_START>07/01/2009 12:12:11</user:DATE_START> <user:DATE_END>08/01/2009 14:14:11</user:DATE_END> </user:ExportList> </soapenv:Body> </soapenv:Envelope> </pre

  

Response <RESULT>  
Elements SUCCESS True if successful. 
  JOB_ID Identifies the Watson Campaign Automation Background Job created and scheduled for this import. 
  FILE_PATH Identifies the file name of the exported file. 
Example
<envelope:Envelope xmlns="SilverpopApi:EngageService.ListMgmt.UserActions"
  xmlns:envelope="http://schemas.xmlsoap.org/soap/envelope/">
  <envelope:Header/>
  <envelope:Body>
    <RESULT>
      <SUCCESS>TRUE</SUCCESS>
      <JOB_ID>502733</JOB_ID>
      <FILE_PATH>/download/A Test List ‐ All ‐ Jul 16 2009 09‐42‐00 PM.CSV</FILE_PATH>
    </RESULT>
  </envelope:Body>
</envelope:Envelope>

  

Add a Column to a Database

AddListColumn

This interface allows adding a column to an existing Watson Campaign Automation database.

Operation <AddListColumn>
Elements LIST_ID The ID of the Watson Campaign Automation database the column is being added to. 
  COLUMN_NAME The name of the column being added.
  COLUMN_TYPE

Defines what type of column to create. The following is a list of valid values:

0 – Text column

1 – YES/No column

2 – Numeric column

3 – Date column

4 – Time column

5 – Country column

6 – Select one

8 – Segmenting

17 – Timestamp

20 – Multi‐Select

  DEFAULT Specifies the default value for the new column. For a multi‐select column, the default value will be a semi‐colon delimited list of values. 
  SELECTION_VALUES Optional Used to define possible values for ‘Select one’ and ‘Multi’Select’ type columns.
    Child Elements VALUE A possible value for a selection column.
Example
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:sil="SilverpopApi:EngageService.SessionHeader"
xmlns:sil1="SilverpopApi:EngageService.ListMgmt.UserActions"> <soapenv:Header> <sil:sessionHeader> <sil:sessionid>07CD20A029FA5D80C97EA0F0B81BD5B0</sil:sessionid> </sil:sessionHeader> </soapenv:Header> <soapenv:Body> <sil1:AddListColumn> <sil1:LIST_ID>90123</sil1:LIST_ID> <sil1:COLUMN_NAME>InterestedIn</sil1:COLUMN_NAME> <sil1:COLUMN_TYPE>20</sil1:COLUMN_TYPE> </sil1:AddListColumn> </soapenv:Body> </soapenv:Envelope>
Response <RESULT>
Elements SUCCESS TRUE if successful.
Example
<envelope:Envelope xmlns:envelope="http://schemas.xmlsoap.org/soap/envelope/">
  <envelope:Header/>
  <envelope:Body xmlns="SilverpopApi:EngageService.ListMgmt.UserActions">
    <RESULT>
      <SUCCESS>true</SUCCESS>
    </RESULT>
  </envelope:Body>
</envelope:Envelope>

Get Database Details

GetListMetaData

This interface returns the description of a Database, Query, or Relational table.

Operation  <GetListMetaData>       
Elements  LIST_ID  Numeric identifier for the entity Watson Campaign Automation is exporting.     
Example 
<:soapenv:Envelope 
  xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:sil="SilverpopApi:EngageService.SessionHeader"
  xmlns:sil1="SilverpopApi:EngageService.ListMgmt.UserActions">:
  <:soapenv:Header>:
    <:sil:sessionHeader>:
      <:sil:sessionid>:07CD20A029FA5D80C97EA0F0B81BD5B0<:/sil:sessionid>:
    <:/sil:sessionHeader>:
  <:/soapenv:Header>:
  <:soapenv:Body>:
    <:sil1:GetListMetaData>:
      <:sil1:LIST_ID>:80750<:/sil1:LIST_ID>:
    <:/sil1:GetListMetaData>:
  <:/soapenv:Body>:
<:/soapenv:Envelope>:
     
Response  <RESULT>       
Elements  SUCCESS  TRUE if successful.     
  ID  Identifies the Database ID.     
  NAME Returns the name of the database.     
  TYPE  Returns the type of database.     
  SIZE  Returns the number of contacts in the database.     
  NUM_OPT_OUTS  Returns the number contacts opted‐out from the database.     
  NUM_UNDELIVERABLE  Returns the number of undeliverable contacts.     
  LAST_MODIFIED  Returns the date Watson Campaign Automation last modified the database.     
  LAST_CONFIGURED  Returns the date Watson Campaign Automation last configured the database.     
  CREATED  Returns the creation date for the database.     
  VISIBILITY 

Returns the visibility of the database. Valid values are:

0 – Private

1 – Shared 

   
  USER_ID  Returns the ID of the user who created the database.     
  ORGANIZATION_ID  Returns the ID for the Organization within which the database was created.     
  OPT_IN_FORM_DEFINED

Specifies whether an Opt‐In form exists for the database.

Values are
True or False. 

   
  OPT_OUT_FORM_DEFINED 

Specifies whether an Opt‐Out form exists for the database.

Values are
True or False. 

   
  PROFILE_FORM_DEFINED 

Specifies whether an Edit Profile form exists for the database.

Values
are True or False. 

   
  OPT_IN_AUTOREPLY_DEFINED 

Specifies whether an Opt‐In Auto‐reply form exists for the database.

Values are True or False. 

   
  PROFILE_AUTOREPLY_DEFINED 

Specifies whether an Edit Profile Auto‐reply form exists for the
database.

Values are True or False. 

   
Optional
Child
Elements 
COLUMN  XML nodes returning the column name of system and custom fields in the database.     
  Child Elements  NAME  Specifies the field name.   
    DEFAULT_VALUE  Specifies the default value for custom fields. For a multi‐select
column, the default value will be a semicolon delimited list of values. 
 
    TYPE 

Specifies the type of custom field. The following is a list of valid values:

0 – Text column

1 – YES/No column

2 –Numeric column

3 – Date column

4 – Time column

5 – Country column

6 – Select one

8 –Segmenting

9 – System (used for defining EMAIL field only)

17 – Timestamp

20 – Multi‐Select 

 
    SELECTION_VALUES  Optional  A list of possible values when column type is Selection or Multi‐Select. 
    Child Elements  VALUE  A single value for a Selection or Multi‐Select column. 
Example  <envelope:Envelope xmlns:envelope="http://schemas.xmlsoap.org/soap/envelope/">
<envelope:Header/>
<envelope:Body xmlns="SilverpopApi:EngageService.ListMgmt.UserActions">
<RESULT>
<SUCCESS>true</SUCCESS>
<ID>80750</ID>
<NAME>CRMI Master List</NAME>
<TYPE>0</TYPE>
<SIZE>123</SIZE>
<NUM_OPT_OUTS>26</NUM_OPT_OUTS>
<NUM_UNDELIVERABLE>0</NUM_UNDELIVERABLE>
<LAST_MODIFIED>11/12/10 04:01 PM</LAST_MODIFIED>
<LAST_CONFIGURED>10/29/10 10:05 AM</LAST_CONFIGURED>
<CREATED>12/18/09 09:09 AM</CREATED>
<VISIBILITY>1</VISIBILITY>
<USER_ID>1f78388‐12551987728‐
6daca699e65990d0e2d42de841d44e31</USER_ID>
<ORGANIZATION_ID>1dcd49d‐108b594203df528764d624db129b32c21fbca0cb8d6</
ORGANIZATION_ID>
<OPT_IN_FORM_DEFINED>false</OPT_IN_FORM_DEFINED>
<OPT_OUT_FORM_DEFINED>false</OPT_OUT_FORM_DEFINED>
<PROFILE_FORM_DEFINED>false</PROFILE_FORM_DEFINED>
<OPT_IN_AUTOREPLY_DEFINED>false</OPT_IN_AUTOREPLY_DEFINED>
<PROFILE_AUTOREPLY_DEFINED>false</PROFILE_AUTOREPLY_DEFINED>
<SMS_KEYWORD/>
<COLUMNS>
<COLUMN>
<NAME>LIST_ID</NAME>
</COLUMN>
<COLUMN>
<NAME>MAILING_ID</NAME>
</COLUMN>
<COLUMN>
<NAME>RECIPIENT_ID</NAME>
</COLUMN>
<COLUMN>
<NAME>EMAIL</NAME>
</COLUMN>
<COLUMN>
<NAME>AGE</NAME>
<DEFAULT_VALUE/>
<TYPE>2</TYPE>
</COLUMN>
<COLUMN>
<NAME>businessTime</NAME>
<DEFAULT_VALUE/>
<TYPE>20</TYPE>
<SELECTION_VALUES/>
</COLUMN>
<COLUMN>
<NAME>companyName</NAME>
<DEFAULT_VALUE/>
<TYPE>0</TYPE>
</COLUMN>
</COLUMNS>
<KEY_COLUMNS>
<COLUMN>
<NAME>EMAIL</NAME>
</COLUMN>
</KEY_COLUMNS>
</RESULT>
</envelope:Body>
</envelope:Envelope> 
     

List Contact Mailings

ListRecipientMailings

This interface returns a list of mailings for a specified database (or query) and contact as well as metrics associated with those mailings.

Note: This operation only returns mailings with associated events (for example, Open, Clickthrough, and Bounce).

Operation  <ListRecipientMailings>     
Elements  LIST_ID  Unique ID of the database or query whose mailings you are requesting.   
  RECIPIENT_ID  Unique ID of the contact for whom to look up mailings.   
Example  <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:sil="SilverpopApi:EngageService.SessionHeader"
xmlns:sil1="SilverpopApi:EngageService.ListMgmt.UserActions">
<soapenv:Header>
<sil:sessionHeader>
<sil:sessionid>221F8D72AEA8D6BA82D32C590396F031</sil:sessionid>
</sil:sessionHeader>
</soapenv:Header>
<soapenv:Body>
<sil1:ListRecipientMailings>
<sil1:LIST_ID>24872</sil1:LIST_ID>
<sil1:RECIPIENT_ID>28052753</sil1:RECIPIENT_ID>
</sil1:ListRecipientMailings>
</soapenv:Body>
</soapenv:Envelope> 
   
Response  <RESULT>     
Elements  SUCCESS  True if successful.  
  Mailing  Zero or more XML nodes containing the definition of each mailing. Each node must contain all of the following elements.   
  Child Element  MailingName  Name of the mailing (enclosed in CDATA tags). 
    MailingId  Unique ID of the mailing. 
    SentTS  Time Watson Campaign Automation sent the mailing. 
    TotalOpens  Total messages opened. 
    TotalClickstreams  Total clickstreams clicked. 
    TotalClicks  Total links clicked. 
    TotalConversions  Total link conversions. 
    TotalAttachments  Total attachments opened. 
    TotalForwards  Total times message was forwarded. 
    TotalMediaPlays  Total times media was played. 
    TotalBounces  Total bounces. 
    TotalOptOuts  Total times opted out of mailings. 
Example  <envelope:Envelope xmlns:envelope="http://schemas.xmlsoap.org/soap/envelope/">
<envelope:Header/>
<envelope:Body xmlns="SilverpopApi:EngageService.ListMgmt.UserActions">
<RESULT>
<SUCCESS>true</SUCCESS>
<Mailing>
<MailingId>800780</MailingId>
<ReportId>66323909</ReportId>
<MailingName>AAT_Optin (1)</MailingName>
<SentTS/>
<TotalOpens>1</TotalOpens>
<TotalClickstreams>0</TotalClickstreams>
<TotalClicks>0</TotalClicks>
<TotalConversions>0</TotalConversions>
<TotalAttachments>0</TotalAttachments>
<TotalForwards>0</TotalForwards>
<TotalMediaPlays>0</TotalMediaPlays>
<TotalBounces>0</TotalBounces>
<TotalOptOuts>0</TotalOptOuts>
</Mailing>
</RESULT>
</envelope:Body>
</envelope:Envelope> 
   

Remove a Contact

RemoveRecipient

Use this interface to remove a contact from a database or Contact List. If your database has a key other than Email, you must include all unique key columns with their corresponding name/value pairs. If your database has
no Unique Identifier defined, one or more Sync Fields must be specified in order to look up the contact.

Operation  <RemoveRecipient>     
Elements  LIST_ID  Unique ID of the database or Contact List from which to remove contact.   
  EMAIL  Email address of the contact to remove.   
  COLUMN  Optional 

Required if the database has a key other than Email or
no Unique Identifier. XML nodes defining the column
name and value used to look up a contact in a database or Contact List. You must include all unique key columns
with their corresponding name/value pairs when using this operation on a database having a key other than
EMAIL.

Note: If more than one contact is found
matching the lookup columns, all contacts will be removed. 

  Child Element  Name  Specifies the field name of a field which is part of the unique key for the database. 
    Value  Specifies the value for the field. 
Example  <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ses="SilverpopApi:EngageService.SessionHeader"
xmlns:user="SilverpopApi:EngageService.ListMgmt.UserActions">
<soapenv:Body>
<user:RemoveRecipient>
<user:LIST_ID>24872</user:LIST_ID>
<user:EMAIL>somebody@domain.com</user:EMAIL>
</user:RemoveRecipient>
</soapenv:Body>
</soapenv:Envelope> 
   
Response  <RESULT>     
Elements  SUCCESS  True if successful.   
  ORGANIZATION_ID  Identifies your Watson campaign Automation Organization.   
Example  <envelope:Envelope xmlns="SilverpopApi:EngageService.ListMgmt.UserActions"
xmlns:envelope="http://schemas.xmlsoap.org/soap/envelope/">
<envelope:Header/>
<envelope:Body>
<RESULT>
<SUCCESS>TRUE</SUCCESS>
</RESULT>
</envelope:Body>
</envelope:Envelope> 
   

Get a List of Databases

GetLists

This interface extracts a list of databases for an organization.

Operation <GetLists>       
Elements VISIBILITY 

Required. Defines the visibility of the databases to return.

0 – Private

1 – Shared 

   
  LIST_TYPE 

Defines the type of entity to return. Supported values are:

0 – Databases

1 – Queries

2 – Both Databases and Queries

5 – Test Lists

6 – Seed Lists

13 – Suppression Lists

15 – Relational Tables

18 – Contact Lists

 

   
  FOLDER_ID  Optional parameter to specify a particular folder from which to return databases.     
  INCLUDE_ALL_LISTS 

Optional parameter to specify that Watson Campaign Automation return all databases within subfolders. Valid
values are True and False.

Note: Watson Campaign Automation will ignore the FOLDER_ID element if set to True. 

   
  INCLUDE_TAGS  Optional parameter to return all Tags associated with the database.     
Example  <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:sil="SilverpopApi:EngageService.SessionHeader"
xmlns:sil1="SilverpopApi:EngageService.ListMgmt.UserActions">
<soapenv:Header>
<sil:sessionHeader>
<sil:sessionid>C28F46937CD55F61A767FF5E99A022EC</sil:sessionid>
</sil:sessionHeader>
</soapenv:Header>
<soapenv:Body>
<sil1:GetLists>
<sil1:VISIBILITY>1</sil1:VISIBILITY>
<sil1:LIST_TYPE>2</sil1:LIST_TYPE>
</sil1:GetLists>
</soapenv:Body>
</soapenv:Envelope> 
     
Response  <RESULT>       
Elements  SUCCESS  True if successful.     
  LIST  XML nodes defining each database.     
  Child Element  ID  Returns the unique ID of the entity.   
    NAME  Returns the name of the entity.   
    TYPE 

Returns the type. Possible values are:
0-Databases

1 – Queries

2 – Both Databases and Queries

5 – Test Lists

6 – Seed Lists

13 – Suppression Lists

15 – Relational Tables 

 
    SIZE  Returns the number of contacts in the database.   
    NUM_OPT_OUTS  Returns the number of opted‐out contacts in the database.   
    NUM_UNDELIVERABLE  Returns the number of undeliverable contacts in the database.   
    LAST_MODIFIED  Returns the date and time when the database was last
modified. 
 
    VISIBILITY  Returns the visibility of the database (for example, Shared or
Private). 
 
    PARENT_NAME  Returns the name of the associated parent folder.   
    USER_ID  Returns the User ID for the database owner.   
    PARENT_FOLDER_ID  Returns the ID of the folder within which the database resides.   
    IS_FOLDER  Returns True if the entity is a folder rather than a database,
query, or relational table. 
 
    Tags  If INCLUDE_TAGS is specified in the request, returns any tags
associated with the database. 
 
      Tag  XML nodes containing the Tags
associated with the database. 
Example <envelope:Envelope xmlns:envelope="http://schemas.xmlsoap.org/soap/envelope/">
<envelope:Header/>
<envelope:Body xmlns="SilverpopApi:EngageService.ListMgmt.UserActions">
<RESULT>
<SUCCESS>true</SUCCESS>
<LIST>
<ID>17383</ID>
<NAME>ATestFolder</NAME>
<TYPE>0</TYPE>
<SIZE>0</SIZE>
<NUM_OPT_OUTS>0</NUM_OPT_OUTS>
<NUM_UNDELIVERABLE>0</NUM_UNDELIVERABLE>
<LAST_MODIFIED>05/14/08 04:10 PM</LAST_MODIFIED>
<VISIBILITY>1</VISIBILITY>
<PARENT_NAME/>
<USER_ID>19c2347‐11929e0fe49‐3652cd0ad7b4125d323423bf450b7c72</USER_ID>
<PARENT_FOLDER_ID>4085</PARENT_FOLDER_ID>
<IS_FOLDER>true</IS_FOLDER>
<FLAGGED_FOR_BACKUP>false</FLAGGED_FOR_BACKUP>
<SUPPRESSION_LIST_ID>0</SUPPRESSION_LIST_ID>
<SUPPRESSION_LIST_ID>0</SUPPRESSION_LIST_ID>
</LIST>
<LIST>
<ID>82537</ID>
<NAME>CW</NAME>
<TYPE>1</TYPE>
<SIZE>0</SIZE>
<NUM_OPT_OUTS>0</NUM_OPT_OUTS>
<NUM_UNDELIVERABLE>0</NUM_UNDELIVERABLE>
<LAST_MODIFIED>02/01/10 11:41 AM</LAST_MODIFIED>
<VISIBILITY>1</VISIBILITY>
<PARENT_NAME/>
<USER_ID>4b695b‐12647e94a9b‐6daca699e65990d0e2d42de841d44e31</USER_ID>
<PARENT_FOLDER_ID>4085</PARENT_FOLDER_ID>
<IS_FOLDER>true</IS_FOLDER>
<FLAGGED_FOR_BACKUP>false</FLAGGED_FOR_BACKUP>
<SUPPRESSION_LIST_ID>0</SUPPRESSION_LIST_ID>
<SUPPRESSION_LIST_ID>0</SUPPRESSION_LIST_ID>
</LIST>
</RESULT>
</envelope:Body>
</envelope:Envelope>
     

Create a Relational Table

CreateTable

This interface creates a Relational Table in Watson Campaign Automation.

Operation  <CreateTable>         
Elements  TABLE_NAME  Defines the name of the new table.       
  COLUMNS 

XML nodes defining the table columns you are inserting/updating.

Note: Unique key columns must be part of the submission with column names and values. 

     
  Elements  COLUMN       
    Child Elements  NAME  Defines the name of the column.   
      TYPE 

Defines what type of column to create. The following is a list of valid values:

TEXT

YESNO

NUMERIC

DATE

TIME

COUNTRY

SELECTION

EMAIL

DATE_TIME

SYNC_ID

 
      IS_REQUIRED  Defines whether to create the column as "required". Valid
values are True and False. 
 
      KEY_COLUMN  Added to field definition and defines a field as a unique key for the table when set to True. You can define more
than one unique field for each table. 
 
      DEFAULT_VALUE  Defines the default value of the column if the row does not
contain a value for this column. 
 
      SELECTION_VALUES  Defines values in a drop‐down list. You must provide at
least one VALUE element for when TYPE = SELECTION. 
 
      VALUE  A single value in a drop‐down list.   
Example  <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:sil="SilverpopApi:EngageService.SessionHeader"
xmlns:sil1="SilverpopApi:EngageService.ListMgmt.UserActions">
<soapenv:Header>
<sil:sessionHeader>
<sil:sessionid>6502C4C303939946C0A14683DAAF8EC5</sil:sessionid>
</sil:sessionHeader>
</soapenv:Header>
<soapenv:Body>
<sil1:CreateTable>
<sil1:TABLE_NAME>Purchase History</sil1:TABLE_NAME>
<sil1:COLUMNS>
<sil1:COLUMN>
<sil1:NAME>Record Id</sil1:NAME>
<sil1:TYPE>NUMERIC</sil1:TYPE>
<sil1:IS_REQUIRED>true</sil1:IS_REQUIRED>
<sil1:KEY_COLUMN>true</sil1:KEY_COLUMN>
</sil1:COLUMN>
<sil1:COLUMN>
<sil1:NAME>Purchase Date</sil1:NAME>
<sil1:TYPE>DATE</sil1:TYPE>
<sil1:IS_REQUIRED>true</sil1:IS_REQUIRED>
</sil1:COLUMN>
<sil1:COLUMN>
<sil1:NAME>Product Id</sil1:NAME>
<sil1:TYPE>NUMERIC</sil1:TYPE>
<sil1:IS_REQUIRED>true</sil1:IS_REQUIRED>
</sil1:COLUMN>
</sil1:COLUMNS>
</sil1:CreateTable>
</soapenv:Body>
</soapenv:Envelope> 
       
Response  <RESULT>         
Elements  SUCCESS  TRUE if successful       
  TABLE_ID  Identifies the Id of the relational table created in Watson Campaign Automation.       
Example  <envelope:Envelope xmlns:envelope="http://schemas.xmlsoap.org/soap/envelope/">
<envelope:Header/>
<envelope:Body xmlns="SilverpopApi:EngageService.ListMgmt.UserActions">
<RESULT>
<SUCCESS>true</SUCCESS>
<TABLE_ID>131126</TABLE_ID>
</RESULT>
</envelope:Body>
</envelope:Envelope> 
       

Associate Relational Data with Contacts in a Database

JoinTable

This interface supports associating a Database with a Relational Table. You must specify a table (name or ID) and database (name or ID) along with the contact columns making the association. Below is the syntax forthe API request and response:

Operation  <JoinTable>     
Elements  TABLE_NAME 

Optional parameter to specify the folder path and name of the Relational Table you are associating. Either TABLE_NAME or TABLE_ID is required.

Note: If you specify TABLE_VISIBILITY, Watson Campaign Automation will ignore Private / Shared in TABLE_NAME. 

 
  TABLE_ID 

Optional parameter to specify the ID of the Relational Table you are joining. Either TABLE_NAME or TABLE_ID is required.

Note: Private/Shared is not specified as part of the path. 

 
  TABLE_VISIBILITY 

Optional field defining the visibility of the table you are referencing. Required if not
specified in TABLE_NAME.

0 – Private

1 – Shared 

 
  LIST_NAME 

Optional parameter specifying the folder path and name of the database you are
associating. Either LIST_NAME or LIST_ID is required.

Note: If you specify LIST_VISIBILITY, Engage will ignore Private / Shared in LIST_NAME. 

 
  LIST_ID  Optional parameter to specify the ID of the database you are associating. Either
LIST_NAME or LIST_ID is required. 
 
  LIST_VISIBILITY 

Optional field defining the visibility of the database you are referencing. Required if not specified in LIST_NAME.

0 – Private

1 – Shared 

 
  REMOVE  Optional Boolean element used to remove the relationship between a database and a Relational Table. If specified, Watson Campaign Automation ignores any MAP_FIELD elements.   
  EMAIL  Optional parameter to specify an email address for notification of job completion or errors.   
Child
Element 
MAP_FIELD     
  Child Elements  LIST_FIELD  Contains the field name in the Watson Campaign Automation database. 
    TABLE_FIELD  Contains the field name in the Relational Table. 
Example  <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ses="SilverpopApi:EngageService.SessionHeader"
xmlns:user="SilverpopApi:EngageService.ListMgmt.UserActions">
<soapenv:Header>
<ses:sessionHeader>
<ses:sessionid>50F4F411A048A4DDA159ABE2954E4610</ses:sessionid>
</ses:sessionHeader>
</soapenv:Header>
<soapenv:Body>
<user:ImportTable>
<user:MAP_FILE>Pets_Table.xml</user:MAP_FILE>
<user:SOURCE_FILE>Pets_Table.csv</user:SOURCE_FILE>
</user:ImportTable>
</soapenv:Body>
</soapenv:Envelope> 
   
Response  <RESULT>     
Elements  SUCCESS  TRUE if successful   
  JOB_ID  Identifies the Watson Campaign Automation Background Job created and scheduled for this process.   
Example  <envelope:Envelope xmlns="SilverpopApi:EngageService.ListMgmt.UserActions"
xmlns:envelope="http://schemas.xmlsoap.org/soap/envelope/">
<envelope:Header/>
<envelope:Body>
<RESULT>
<SUCCESS>TRUE</SUCCESS>
<JOB_ID>273287</JOB_ID>
</RESULT>
</envelope:Body>
</envelope:Envelope> 
   

Insert and Update Records in a Relational Table

InsertUpdateRelationalTable

This interface inserts or updates relational data.

For each Row that is passed in:

  • If a row is found having the same key as the passed in row, update the record.
  • If no matching row is found, insert a new row setting the column values to those passed in the request.

When rows are inserted or updated in the relational table, all Column values are set based on the values passed in the COLUMN elements.

Note: Only one hundred rows may be passed in a single InsertUpdateRelationalTable call.

Operation  <InsertUpdateRelationalTable>         
Elements  TABLE_ID  The Id of the Watson Campaign Automation Table that will be updated.       
  ROWS  XML node containing ROW elements for each row being inserted or updated.       
  Child
Elements 
ROW  XML nodes defining a relational table row and its columns.     
    Child
Elements 
COLUMN  The value of the Relational Table Column being inserted or
updated. 
 
      Attributes  name  The name of the Relational Table Column being
inserted or updated. 
Example <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:sil="SilverpopApi:EngageService.SessionHeader"
xmlns:sil1="SilverpopApi:EngageService.ListMgmt.UserActions">
<soapenv:Header>
<sil:sessionHeader>
<sil:sessionid>6502C4C303939946C0A14683DAAF8EC5</sil:sessionid>
</sil:sessionHeader>
</soapenv:Header>
<soapenv:Body>
<sil1:InsertUpdateRelationalTable>
<sil1:TABLE_ID>131126</sil1:TABLE_ID>
<sil1:ROWS>
<sil1:ROW>
<sil1:COLUMN name="Record Id"><![CDATA[15465431]]></sil1:COLUMN>
<sil1:COLUMN name="Purchase Date"><![CDATA[01/09/2010]]></sil1:COLUMN>
<sil1:COLUMN name="Product Id"><![CDATA[12345]]></sil1:COLUMN>
</sil1:ROW>
<sil1:ROW>
<sil1:COLUMN name="Record Id"><![CDATA[54646654]]></sil1:COLUMN>
<sil1:COLUMN name="Purchase Date"><![CDATA[10/11/2010]]></sil1:COLUMN>
<sil1:COLUMN name="Product Id"><![CDATA[7979]]></sil1:COLUMN>
</sil1:ROW>
</sil1:ROWS>
</sil1:InsertUpdateRelationalTable>
</soapenv:Body>
</soapenv:Envelope> 
       
Response  <RESULT>         
Elements  SUCCESS  True if the request is successfully received and processed.       
  FAILURES  XML node containing FAILURE elements for each row that could NOT be inserted
or updated. This element and its children will not be included if no failures are
encountered. 
     
  Child Elements  FAILURE  Provides a type and description of each failure.     
  Attributes  failure_type 

Identifies whether the row could not be inserted or updated for a reason that is temporary. Valid values are:

transient

permanent 

   
    description  The description of the error.     
    Child Elements  COLUMN 

The value of the Relational Table Column being
inserted or updated.

A COLUMN will be
returned for each field of the record that could
not be inserted. 

 
    Attributes  name  The name of the Relational Table Column being
inserted or updated that was not successful. 
 
Example <envelope:Envelope xmlns:envelope="http://schemas.xmlsoap.org/soap/envelope/">
<envelope:Header/>
<envelope:Body xmlns="SilverpopApi:EngageService.ListMgmt.UserActions">
<RESULT>
<SUCCESS>true</SUCCESS>
<FAILURES></FAILURES>
</RESULT>
</envelope:Body>
</envelope:Envelope>
       

Delete Records From a Relational Table

DeleteRelationalTableData

This interface deletes records from a relational table.

Operation  <DeleteRelationalTableData>         
Elements  TABLE_ID  The Id of the Watson Campaign Automation Table that will be updated.       
  ROWS  XML node containing ROW elements for each row being deleted.       
  Child Elements  ROW  XML nodes defining a relational table row and its key columns.     
    Child
Elements
KEY_COLUMN  The value of a Relational Table Key Column for
the row being deleted. If the table has multiple
columns defined as key columns, each ROW
will have multiple KEY_COLUMN elements. All Key Columns must be provided for each ROW. 
 
      Attributes  name  The name of a Relational Table
Key Column for the row being
deleted. 
Example  <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:sil="SilverpopApi:EngageService.SessionHeader"
xmlns:sil1="SilverpopApi:EngageService.ListMgmt.UserActions">
<soapenv:Header>
<sil:sessionHeader>
<sil:sessionid>6502C4C303939946C0A14683DAAF8EC5</sil:sessionid>
</sil:sessionHeader>
</soapenv:Header>
<soapenv:Body>
<sil1:DeleteRelationalTableData>
<sil1:TABLE_ID>131126</sil1:TABLE_ID>
<sil1:ROWS>
<sil1:ROW>
<sil1:KEY_COLUMN name="Record Id"><![CDATA[15465431]]></sil1:KEY_COLUMN>
<sil1:KEY_COLUMN name="Record Id"><![CDATA[54646654]]></sil1:KEY_COLUMN>
</sil1:ROW>
</sil1:ROWS>
</sil1:DeleteRelationalTableData>
</soapenv:Body>
</soapenv:Envelope> 
       
Response  <RESULT>         
Elements  SUCCESS  True if any rows are deleted.       
  FAILURES  XML node containing FAILURE elements for each row that could NOT be deleted.       
  Child Elements  FAILURE  Provides a description of each failure.     
  Attributes  failure_type 

Identifies whether the row could not be deleted for a reason
that is temporary.

Valid values are:

transient

permanent 

   
    description  The description of the error.     
    Child Elements  KEY_COLUMN  The value of a Relational Table Key Column
for the row being deleted. A KEY_COLUMN
will be returned for each key field of the record that could not be inserted. 
 
    Attributes  name  The name of the Relational Table Key
Column being deleted that was not
successful. 
 
Example  <envelope:Envelope xmlns:envelope="http://schemas.xmlsoap.org/soap/envelope/">
<envelope:Header/>
<envelope:Body xmlns="SilverpopApi:EngageService.ListMgmt.UserActions">
<RESULT>
<SUCCESS>true</SUCCESS>
<FAILURES></FAILURES>
</RESULT>
</envelope:Body>
</envelope:Envelope> 
       

Import to a Relational Table

ImportTable

This interface is used for programmatically creating or updating a Relational Table in Watson Campaign Automation. This operation requires a mapping file and source file stored on the FTP server related to the Watson Campaign Automation account used to Login. Once you upload the Relational Table source and mapping files to the FTP server, you can make an ImportTable API call to launch the job.

Note: This operation does not associate the relational table to a database. See "Associate Relational Data to Contacts in a Database" for creating the association.

The table below shows the syntax for the API request and response.

Operation  <ImportTable>   
Elements  MAP_FILE  The name of the Mapping file in the upload directory on the FTP server to use for the
import. 
  SOURCE_FILE The name of the file containing the Relational Table data to use in the import. This file must reside in the upload directory on the FTP server. 
Example  <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ses="SilverpopApi:EngageService.SessionHeader"
xmlns:user="SilverpopApi:EngageService.ListMgmt.UserActions">
<soapenv:Header>
<ses:sessionHeader>
<ses:sessionid>50F4F411A048A4DDA159ABE2954E4610</ses:sessionid>
</ses:sessionHeader>
</soapenv:Header>
<soapenv:Body>
<user:ImportTable>
<user:MAP_FILE>Pets_Table.xml</user:MAP_FILE>
<user:SOURCE_FILE>Pets_Table.csv</user:SOURCE_FILE>
</user:ImportTable>
</soapenv:Body>
</soapenv:Envelope> 
 
Response  <RESULT>   
Elements  SUCCESS  True if successful. 
  JOB_ID  Identifies the Watson Campaign Automation Background Job created and scheduled for this import. 
Example  <envelope:Envelope xmlns="SilverpopApi:EngageService.ListMgmt.UserActions"xmlns:envelope="http://schemas.xmlsoap.org/soap/envelope/">
<envelope:Header/>
<envelope:Body>
<RESULT>
<SUCCESS>TRUE</SUCCESS>
<JOB_ID>273287</JOB_ID>
</RESULT>
</envelope:Body>
</envelope:Envelope> 
 

Relational Table Definition and Column Mapping Format

Mapping is the process of associating columns in the import file with the corresponding fields in the Relational Table. For example, Column 1 in the file corresponds to Purchase Date in the Purchases Relational Table.

The Relational Table Mapping XML file is broken into three main sections:

  1. TABLE_INFO – defines the information about the table you are creating or updating, as well as the action to perform on this table.
  2. COLUMNS – consists of one or more COLUMN elements. Each COLUMN element contains child elements to define the attributes for that column (for example, name, type, and key column).
  3. MAPPING – also consists of COLUMN elements. Each COLUMN element contains child elements to define the attributes for mapping that column (for example, name or index).

Note: All column names are case‐sensitive. The Mapping file and Relational Data file field names must exactly match the case and content in the existing Relational Table.

The table below describes each section to include with a LIST_IMPORT element:

Section  <TABLE_INFO> The TABLE_INFO section defines information about the table you are creating or updating, as well as the action to perform on this table.   
Elements  ACTION

Defines the type of Relational Table import you are executing. Valid values (and the
actions they perform) are:

CREATE – create a new Relational Table.

ADD_ONLY – only add new records to the table. Watson Campaign Automation ignores existing (duplicate) records in the source file.

UPDATE_ONLY – only update existing records in the table. Watson Campaign Automation ignores records found
in the source file but not in the Relational Table.

ADD_AND_UPDATE – process all records in the source file. If the item already exists in
the Relational Table, update specified field values. If the item does not exist, create a new record in the Relational Table.

REPLACE – deletes all records from the Relational Table and adds new records to the
table.

 

 
  TABLE_NAME  Defines the name of the new Relational Table if the ACTION is CREATE (table names must be unique).   
  TABLE_VISIBILITY 

Defines the visibility of the table. If not included, Watson Campaign Automation will set to Private.

0 – Private

1 – Shared

 

 
  PARENT_FOLDER_PATH 

Used with the CREATE ACTION to specify the folder within which to place the new table.

Use the VISIBILITY element to specify Private or Shared. 

 
  FILE_TYPE 

Defines the formatting of the source file. Supported values are:

0 – CSV file

1 – Tab‐separated file

2 – Pipe‐separated file

 

 
  HASHEADERS  The HASHEADERS element is set to True if the first line in the source file contains column definitions.   
Section  <COLUMNS>  The HASHEADERS element is set to True if the first line in the source file contains column definitions.   
Elements  COLUMN     
  Child Elements  NAME  Defines the name of the column. 
    TYPE 

Defines what type of column to create. The valid values are:

0 – Text column

1 – Yes/No column

2 – Numeric column

3 – Date column

4 – Time column

5 – Country column

6 – Select One

7 – Email

17 – Date/Time

19 – Sync ID

 

    IS_REQUIRED 

Defines whether to create the column as Required when contacts are providing information through a form. Valid values are True and False.

Note: The import process does use this to validate the data. 

    KEY_COLUMN  Added to field definition and set to True to define a field as a unique
key for the Relational Table. You can define more than one unique field for the table to create a composite key. 
    DEFAULT_VALUE  Defines the default value of the column used by the Send process if the record does not contain a value for this column. 
Section  <MAPPING>  The MAPPING section tells the Relational Table Import process which columns in the source file map to which columns in the Watson Campaign Automation Relational Table. Define each table column in its own COLUMN element.   
Elements  COLUMN     
  Child Elements  INDEX  The INDEX element defines the order within which to define this
column in the source file. 
    NAME  The name of the TABLE column to which to map the column in the source file. 
    INCLUDE  Defines if this element is included in the table import. You do not need to import all columns from the source file. This element allows you to direct the Relational Table Import process to skip the columns
you don't want to include. Valid values are True and False. 

Example Mapping File

Example  This example shows a mapping file for creating a new Relational Table related to an existing list. Customer ID and Purchase Date make up the key for the new table: 
  <TABLE_IMPORT>
<TABLE_INFO>
<ACTION>CREATE</ACTION>
<TABLE_NAME>Purchases</TABLE_NAME>
<FILE_TYPE>0</FILE_TYPE>
<HASHEADERS>true</HASHEADERS>
</TABLE_INFO>
<COLUMNS>
<COLUMN>
<NAME>Customer ID</NAME>
<TYPE>0</TYPE>
<IS_REQUIRED>true</IS_REQUIRED>
<KEY_COLUMN>true</KEY_COLUMN>
</COLUMN>
<COLUMN>
<NAME>Purchase Date</NAME>
<TYPE>3</TYPE>
<IS_REQUIRED>true</IS_REQUIRED>
<KEY_COLUMN>true</KEY_COLUMN>
</COLUMN>
<COLUMN>
<NAME>Product ID</NAME>
<TYPE>0</TYPE>
<IS_REQUIRED>true</IS_REQUIRED>
<DEFAULT_VALUE/>
</COLUMN>
</COLUMNS>
<MAPPING>
<COLUMN>
<INDEX>1</INDEX>
<NAME>Customer ID</NAME>
<INCLUDE>true</INCLUDE>
</COLUMN>
<COLUMN>
<INDEX>2</INDEX>
<NAME>Purchase Date</NAME>
<INCLUDE>true</INCLUDE>
</COLUMN>
<COLUMN>
<INDEX>3</INDEX>
<NAME>Product ID</NAME>
<INCLUDE>true</INCLUDE>
</COLUMN>
</MAPPING>
</TABLE_IMPORT> 

Export from a Relational Table

ExportTable

This interface supports programmatically exporting Relational Table data from Watson Campaign Automation into a CSV file, which Watson Campaign Automation uploads to the FTP account or to the Stored Files directory associated with the session.

Below is the syntax for the API request and response:

Operation  <ExportTable>     
Elements  TABLE_NAME

Optional parameter specifying the folder path and name of the Relational Table you are exporting. Either TABLE_NAME or TABLE_ID is required.

Note: If you specify TABLE_VISIBILITY, Watson Campaign Automation ignores Private / Shared in TABLE_NAME. 

 
  TABLE_ID 

Optional parameter to specify the ID of the Relational Table you are exporting. Either TABLE_NAME or TABLE_ID is required.

Note: Watson Campaign Automation does not specify Private or Shared as part of the path. 

 
  TABLE_VISIBILITY 

Optional field defining the visibility of the table you are referencing. Required if not
specified in TABLE_NAME.

0 – Private

1 – Shared

 

 
  EMAIL  Optional  If specified, Watson Campaign Automation sends a notification email to the provided email
address when the job is complete. 
  EXPORT_FORMAT 

Specifies the file format for the exported data. Valid values are:

CSV – create a comma‐separated values file

TAB – create a tab‐separated values file

PIPE – create a pipe‐separated values file

 

 
  ADD_TO_STORED_FILES  Optional  Use the ADD_TO_STORED_FILES parameter to write output to the Stored Files folder in Watson Campaign Automation. If you omit this parameter, Watson Campaign Automation moves exported files to the download directory of your FTP account. 
  DATE_START  Optional  Specifies the beginning boundary of information to export (relative to
the last modified date of the contact). If time is included, it must be in
24‐hour format. 
  DATE_END  Optional  Specifies the ending boundary of information to export (relative to
the last modified date of the contact). If time is included, it must be in
24‐hour format. 
Example  <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ses="SilverpopApi:EngageService.SessionHeader"
xmlns:user="SilverpopApi:EngageService.ListMgmt.UserActions">
<soapenv:Header>
<ses:sessionHeader>
<ses:sessionid>16FE7B75445E6C704707025B1B7BBEE5</ses:sessionid>
</ses:sessionHeader>
</soapenv:Header>
<soapenv:Body>
<user:ExportTable>
<user:TABLE_NAME>Private/Friends</user:TABLE_NAME>
<user:EXPORT_FORMAT>CSV</user:EXPORT_FORMAT>
<user:ADD_TO_STORED_FILES/>
<user:DATE_START>06/07/2009 24:00:00</user:DATE_START>
<user:DATE_END>06/09/2009 24:00:00</user:DATE_END>
</user:ExportTable>
</soapenv:Body>
</soapenv:Envelope> 
   
Response  <RESULT>     
Elements  SUCCESS  TRUE if successful   
  JOB_ID  Identifies the Watson Campaign Automation Background Job created and scheduled for this export.   
  FILE_PATH  Returns the file name of the export file.   
Example  <envelope:Envelope xmlns="SilverpopApi:EngageService.ListMgmt.UserActions"
xmlns:envelope="http://schemas.xmlsoap.org/soap/envelope/">
<envelope:Header/>
<envelope:Body>
<RESULT>
<SUCCESS>TRUE</SUCCESS>
<JOB_ID>503532</JOB_ID>
<FILE_PATH>/download/Friends ‐ All ‐ Jul 17 2009 09‐05‐51 AM.CSV</FILE_PATH>
</RESULT>
</envelope:Body>
</envelope:Envelope> 
   

Purge Data from a Relational Table

PurgeTable

This interface supports programmatically deleting Relational Table data from Watson Campaign Automation. You can purge all data (or specify a date range using "Delete Before"). The table below shows the Purge Table API syntax.

Operation  <PurgeTable>     
Elements  TABLE_NAME 

Parameter to specify the folder path and name of the Relational Table you are
deleting.

Note: Requires either TABLE_NAME or TABLE_ID. If you specify TABLE_VISIBILITY, Watson Campaign Automation ignores Private/Shared in TABLE_NAME. 

 
  TABLE_ID

Parameter specifying the ID of the Relational Table you are deleting.

Note: Requires either TABLE_NAME or TABLE_ID. Watson Campaign Automation does not specify Private/Shared as part of the path. 

 
  TABLE_VISIBILITY 

Parameter defining the visibility of the table you are referencing. Required if not
specified in TABLE_NAME.

0 – Private

1 – Shared

 

 
  DELETE_BEFORE  Optional  If included, only data last modified before the specified date/time
will be purged. 
  EMAIL  Optional  If specified, Watson Campaign Automation sends notification to the provided email address
when the job is complete. 
Example  <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:sil="SilverpopApi:EngageService.SessionHeader"
xmlns:sil1="SilverpopApi:EngageService.ListMgmt.UserActions">
<soapenv:Header>
<sil:sessionHeader>
<sil:sessionid>6502C4C303939946C0A14683DAAF8EC5</sil:sessionid>
</sil:sessionHeader>
</soapenv:Header>
<soapenv:Body>
<sil1:PurgeTable>
<sil1:TABLE_ID>131126</sil1:TABLE_ID>
<sil1:DELETE_BEFORE>07/25/2009 12:12:11</sil1:DELETE_BEFORE>
<sil1:EMAIL>somebody@silverpop.com</sil1:EMAIL>
</sil1:PurgeTable>
</soapenv:Body>
</soapenv:Envelope> 
   
Response  <RESULT>     
Elements  SUCCESS  TRUE if successful   
  JOB_ID  Identifies the Watson Campaign Automation Background Job created and scheduled for this table purge.   
Example  <envelope:Envelope xmlns:envelope="http://schemas.xmlsoap.org/soap/envelope/">
<envelope:Header/>
<envelope:Body xmlns="SilverpopApi:EngageService.ListMgmt.UserActions">
<RESULT>
<SUCCESS>true</SUCCESS>
<JOB_ID>2496711</JOB_ID>
</RESULT>
</envelope:Body>
</envelope:Envelope> 
   

Delete a Relational Table

DeleteTable

The Delete Table API supports programmatically deleting Relational Table data from Watson Campaign Automation. You cannot delete the Relational Table in any of the following cases:

  • When the table is in use by active Group of Automated Messages.
  • If the table is in use by an active Autoresponder.
  • If the table is in use by an active Sending mailing.
  • When queries exist that reference the table, but are owned by an associated database.

You can delete the following:

  • Table data
  • The table entity/structure
  • Database/Table associations (joins)
  • Relational Table queries

Below is the syntax for the API request and response.

Operation  <DeleteTable>     
Elements  TABLE_NAME 

Optional parameter to specify the folder path and name of the Relational Table
you are deleting. Either TABLE_NAME or TABLE_ID is required.

Note: If you specify TABLE_VISIBILITY, Watson Campaign Automation ignores Private/Shared in TABLE_NAME. 

 
  TABLE_ID 

Optional parameter specifying the ID of the Relational Table you are deleting.
Either TABLE_NAME or TABLE_ID is required.

Note: Watson Campaign Automation does not specify Private/Shared as part of the path. 

 
  TABLE_VISIBILITY 

Optional field defining the visibility of the table you are referencing. Required if not
specified in TABLE_NAME.

0 – Private

1 – Shared

 

 
  EMAIL  Optional  If specified, Watson Campaign Automation sends notification to the provided email
address when the job is complete. 
Example  <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ses="SilverpopApi:EngageService.SessionHeader"
xmlns:user="SilverpopApi:EngageService.ListMgmt.UserActions">
<soapenv:Header>
<ses:sessionHeader>
<ses:sessionid>16FE7B75445E6C704707025B1B7BBEE5</ses:sessionid>
</ses:sessionHeader>
</soapenv:Header>
<soapenv:Body>
<user:DeleteTable>
<user:TABLE_NAME>Shared/Product</user:TABLE_NAME>
<user:EMAIL>somebody@domain.com</user:EMAIL>
</user:DeleteTable>
</soapenv:Body>
</soapenv:Envelope> 
   
Response  <RESULT>     
Elements  SUCCESS  TRUE if successful   
  JOB_ID  Identifies the Watson Campaign Automation Background Job created and scheduled for this table deletion.   
Example  <envelope:Envelope xmlns="SilverpopApi:EngageService.ListMgmt.UserActions"
xmlns:envelope="http://schemas.xmlsoap.org/soap/envelope/">
<envelope:Header/>
<envelope:Body>
<RESULT>
<SUCCESS>TRUE</SUCCESS>
<JOB_ID>503533</JOB_ID>
</RESULT>
</envelope:Body>
</envelope:Envelope> 
   

Create Contact List

CreateContactList

This interface creates a new Contact List in Watson Campaign Automation. A jsessionid must be provided to create a Contact List.

Operation  <CreateContactList>   
Elements  DATABASE_ID  The ID of the database the new Contact List will be associated with. 
  CONTACT_LIST_NAME  The name of the Contact List to be created. 
  VISIBILITY 

Defines the visibility of the Contact List being created.

0 – Private

1 – Shared

 

Example  <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:sil="SilverpopApi:EngageService.SessionHeader"
xmlns:sil1="SilverpopApi:EngageService.ListMgmt.UserActions">
<soapenv:Header>
<sil:sessionHeader>
<sil:sessionid>530655D8BFFAC1DAFA448051DFDA6391</sil:sessionid>
</sil:sessionHeader>
</soapenv:Header>
<soapenv:Body>
<sil1:CreateContactList>
<sil1:DATABASE_ID>20274</sil1:DATABASE_ID>
<sil1:CONTACT_LIST_NAME>Premium Contacts</sil1:CONTACT_LIST_NAME>
<sil1:VISIBILITY>0</sil1:VISIBILITY>
</sil1:CreateContactList>
</soapenv:Body>
</soapenv:Envelope> 
 
Response  <RESULT>   
Elements  SUCCESS  True if successful. 
  CONTACT_LIST_ID  The ID of the Contact List that was created. 
Example  <envelope:Envelope xmlns:envelope="http://schemas.xmlsoap.org/soap/envelope/">
<envelope:Header/>
<envelope:Body xmlns="SilverpopApi:EngageService.ListMgmt.UserActions">
<RESULT>
<SUCCESS>true</SUCCESS>
<CONTACT_LIST_ID>131145</CONTACT_LIST_ID>
</RESULT>
</envelope:Body>
</envelope:Envelope> 
 

Add a Contact to a Contact List

AddContactToContactList

This interface adds one new contact to a Contact List. If the contact is not yet in your database, they may be added using the AddRecipient operation (see the "Add a Contact" section).

The contact may be added to the Contact List by providing either a Contact Id or the key fields from the Database. The Contact Id can be obtained from the RecipientId element in the response of the following operations: AddRecipient, UpdateRecipient, and SelectRecipientData.

If providing key fields and your database has a key other than Email, you must include all unique key columns with their corresponding name/value pairs. If using a database that has no Unique Identifier defined, one or more columns must be specified in order to look up the contact.

Upon looking up the contact in the database using the Contact Id or key fields, Watson Campaign Automation will process the contact as follows:

  • If the contact is found and does not yet exist in the Contact List, they will be added.
  • If the contact is found and already exists in the Contact List, they will be not be added.
  • If more than one contact is found matching the Sync Fields for a non‐keyed list, an error message will be returned.
  • If the contact is not found, an error message will be returned.
Operation  <AddContactToContactList>     
Elements  CONTACT_LIST_ID The ID of the Contact List to which you are adding the contact.   
  CONTACT_ID  Optional  The ID of the contact being added to the Contact List. Either a
CONTACT_ID or COLUMN elements must be provided. If
CONTACT_ID is provided, any COLUMN elements will be ignored. 
  COLUMN  Optional

Required if the database has a key other than Email or no Unique
Identifier and Contact Id is not provided. XML nodes defining the
column name and value used to look up a contact in a database.
Ignored for regular email key databases.

Note: Unique key columns
must be part of the submission with column names and values. 

  Child Element  Name  Contains the field name. 
    Value  Contains the field value. 
Example with
Contact Id 
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:sil="SilverpopApi:EngageService.SessionHeader"
xmlns:sil1="SilverpopApi:EngageService.ListMgmt.UserActions">
<soapenv:Header>
<sil:sessionHeader>
<sil:sessionid>530655D8BFFAC1DAFA448051DFDA6391</sil:sessionid>
</sil:sessionHeader>
</soapenv:Header>
<soapenv:Body>
<sil1:AddContactToContactList>
<sil1:CONTACT_LIST_ID>131145</sil1:CONTACT_LIST_ID>
<sil1:CONTACT_ID>23476503</sil1:CONTACT_ID>
</sil1:AddContactToContactList>
</soapenv:Body>
</soapenv:Envelope> 
   
Example with
COLUMN
elements 
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:sil="SilverpopApi:EngageService.SessionHeader"
xmlns:sil1="SilverpopApi:EngageService.ListMgmt.UserActions">
<soapenv:Header>
<sil:sessionHeader>
<sil:sessionid>530655D8BFFAC1DAFA448051DFDA6391</sil:sessionid>
</sil:sessionHeader>
</soapenv:Header>
<soapenv:Body>
<sil1:AddContactToContactList>
<sil1:CONTACT_LIST_ID>131145</sil1:CONTACT_LIST_ID>
<sil1:COLUMN>
<sil1:NAME>SSN</sil1:NAME>
<sil1:VALUE>123‐45‐6789</sil1:VALUE>
</sil1:COLUMN>
<sil1:COLUMN>
<sil1:NAME>First_Name</sil1:NAME>
<sil1:VALUE>Joe</sil1:VALUE>
</sil1:COLUMN>
<sil1:COLUMN>
<sil1:NAME>Last_Name</sil1:NAME>
<sil1:VALUE>Smith</sil1:VALUE>
</sil1:COLUMN>
</sil1:AddContactToContactList>
</soapenv:Body>
</soapenv:Envelope> 
   
Response  <RESULT>     
Elements SUCCESS  True if successful.   
Example  <envelope:Envelope xmlns:envelope="http://schemas.xmlsoap.org/soap/envelope/">
<envelope:Header/>
<envelope:Body xmlns="SilverpopApi:EngageService.ListMgmt.UserActions">
<RESULT>
<SUCCESS>true</SUCCESS>
</RESULT>
</envelope:Body>
</envelope:Envelope> 
   

Add a Contact to a Program

AddContactToProgram

This interface is used to add a Contact to a Program. The Contact will be added to the beginning of the Program.

This operation will typically be used in conjunction with either the AddRecipient or UpdateRecipient operation. After adding or updating a Contact using those operations, the RecipientId in the response can be used in the CONTACT_ID element in a subsequent AddContactToProgram API request.

A valid jsessionid must be provided to authenticate the request.

The contact will not be added if any of the following scenarios exist:

  • The specified CONTACT_ID is already an active participant in the Program.
  • The specified CONTACT_ID is NOT in the database associated with the Program.
  • The specified PROGRAM_ID is Pending and not accepting new Contacts.
  • The specified PROGRAM_ID is Inactive and not accepting new Contacts.
  • The specified PROGRAM_ID is Completed and not accepting new Contacts.
  • The specified PROGRAM_ID has a Last Contact Add Date in the past.
  • The specified PROGRAM_ID does not exist.
Operation  <AddContactToProgram>   
Elements  PROGRAM_ID  Unique ID of the program. 
  CONTACT_ID  Unique ID of the contact being added to the program. 
Example  <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:sil="SilverpopApi:EngageService.SessionHeader"
xmlns:sil1="SilverpopApi:EngageService.ListMgmt.UserActions">
<soapenv:Header>
<sil:sessionHeader>
<sil:sessionid>A64604ED696D782CF898BA2F701F743E</sil:sessionid>
</sil:sessionHeader>
</soapenv:Header>
<soapenv:Body>
<sil1:AddContactToProgram>
<sil1:PROGRAM_ID>129832</sil1:PROGRAM_ID>
<sil1:CONTACT_ID>129832</sil1:CONTACT_ID>
</sil1:AddContactToProgram>
</soapenv:Body>
</soapenv:Envelope> 
 
Response  <RESULT>   
Elements  SUCCESS  True if successful. 
Example  <envelope:Envelope xmlns:envelope="http://schemas.xmlsoap.org/soap/envelope/">
<envelope:Header/>
<envelope:Body xmlns="SilverpopApi:EngageService.ListMgmt.UserActions">
<RESULT>
<SUCCESS>true</SUCCESS>
</RESULT>
</envelope:Body>
</envelope:Envelope> 
 

Create a Query of a Database

CreateQuery

This interface supports programmatically creating a query of a Watson Campaign Automation database. A query can search for values within database columns and also filter by mailing activity.

Operation  <CreateQuery>         
Elements  QUERY_NAME  The name of the new query.       
  PARENT_LIST_ID  The ID of the database being queried.       
  VISIBILITY 

Defining the visibility of the new query. Valid values are:

0 – Private

1 – Shared

 

     
  PARENT_FOLDER_ID Optional  The ID of the folder within which to save the query. If
not specified, it will be stored in the root of Shared or
Private based on VISIBILITY. 
   
  SELECT_COLUMNS Optional  A pipe‐separated list of fields available for
personalization. 
   
  ALLOW_FIELD_CHANGE  Optional 

Defines whether to allow users to change the fields available for personalization when editing or creating a
new query from this query. If not specified, the default will be 1 (Allow Changes).Valid values are:

0 – Do not allow changes

1 – Allow Changes

 

   
Child
Element 
CRITERIA  Describes the expressions to perform on one or more columns in the database.       
  Child Element  TYPE  Optional 

Specifies if criteria are locked or editable. Valid values
are:

Locked

Editable

If not specified, the default will be marked Editable.

 

 
    EXPRESSION  Describes a single expression to perform on a column. One or more
EXPRESSION elements can exist within the CRITERIA element. 
   
    Child Element  TYPE 

The type of evaluation. Valid values are:

NE – Numeric

DE – Date/Time

TE – Text

 

 
      COLUMN_NAME The name of the database field.   
      OPERATORS 

The operator used for comparison. Valid values are:

!=

<

>

=

IS NOT null

IS null

LIKE

NOT like

IN

NOT in

BETWEEN

 

 
      VALUES  Optional  The value being compared to the Watson campaign Automation
database field. This can include text or a
numeric or date value. It can also include a
list of values or the name of a Column. If
specifying a Database Column, surround
with square brackets, such as: [My Text Column]. If specifying a list of values, use
the pipe character ( | ) to separate values
in a list. Required for all operators other
than IS NOT null and IS null. 
      LEFT_PARENS  Optional  Used to specify one or more left
parentheses when relating more than one
expression. For example, two left
parentheses would be indicated as: (( 
      RIGHT_PARENS  Optional  Used to specify one or more right
parentheses when relating more than one
expression. For example, two right
parentheses would be indicated as: )) 
      AND_OR  Optional  Used to specify AND or OR when relating
multiple expressions. 
Child
Element 
BEHAVIOR  Optional  Optional; defines the Behavior section of the query. Filters mailing
contacts by their activity. 
   
  Child Element  OPTION_OPERATOR 

Specifies the operation or activity for which you are searching. Valid
values are:

100 – Opened

101 – Clicked

102 – Bounced

103 – No Activity

 

   
    TYPE_OPERATOR 

Specifies whether to search a particular mailing (or all mailings) for
the database. Valid values are:

110 – For Any Mailing (only available if query is on the database
designated to store Automated Behavior Updates)

111 – For One Mailing

 

   
    MAILING_ID  Optional  The ID of the mailing within which to search for contact
activity. 
 
    REPORT_ID  Optional  The Report ID that identifies the mailing instance within
which to search for contact activity. 
 
    LINK_NAME  Optional  The name of a link in a mailing. Used to include only contacts who clicked on a particular link in a mailing.   
      WHERE_OPERATOR  Optional 

Specifies whether to compare to an activity count, date
of activity, or number of days since activity. Valid values
are:

120 – Days Since Activity

121 – Activity Date

122 – Activity Count

Only used when you specify For One Mailing and you do NOT include a No Activity parameter.

 

      CRITERIA_OPERATOR  Optional 

The operator used for comparison. Required if
WHERE_OPERATOR is included. Valid values are:

!=

<

>

=

>=

<=

BETWEEN

 

      VALUES  Optional  The value you are comparing to the contact activity
count, date of activity, or number of days since activity. Could be numeric or date value. If operator is BETWEEN, two values must be provided delimited by a pipe. Required if WHERE_OPERATOR is included. 
Example  <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ses="SilverpopApi:EngageService.SessionHeader"
xmlns:user="SilverpopApi:EngageService.ListMgmt.UserActions">
<soapenv:Header>
<ses:sessionHeader>
<ses:sessionid>16FE7B75445E6C704707025B1B7BBEE5</ses:sessionid>
</ses:sessionHeader>
</soapenv:Header>
<soapenv:Body>
<user:CreateQuery>
<user:QUERY_NAME>Test_Query</user:QUERY_NAME>
<user:PARENT_LIST_ID>24872</user:PARENT_LIST_ID>
<user:VISIBILITY>0</user:VISIBILITY>
<user:ALLOW_FIELD_CHANGE>0</user:ALLOW_FIELD_CHANGE>
<user:SELECT_COLUMNS>EMAIL|First_Name</user:SELECT_COLUMNS>
<user:CRITERIA>
<user:TYPE>editable</user:TYPE>
<user:EXPRESSION>
<user:TYPE>TE</user:TYPE>
<user:COLUMN_NAME>EMAIL</user:COLUMN_NAME>
<user:OPERATORS><![CDATA[LIKE]]></user:OPERATORS>
<user:VALUES><![CDATA[gmail.com]]></user:VALUES>
<user:LEFT_PARENS>(</user:LEFT_PARENS>
</user:EXPRESSION>
<user:EXPRESSION>
<user:AND_OR>AND</user:AND_OR>
<user:TYPE>TE</user:TYPE>
<user:COLUMN_NAME>First_Name</user:COLUMN_NAME>
<user:OPERATORS><![CDATA[IS null]]></user:OPERATORS>
<user:RIGHT_PARENS>)</user:RIGHT_PARENS>
<user:VALUES/>
</user:EXPRESSION>
</user:CRITERIA>
</user:CreateQuery>
</soapenv:Body>
</soapenv:Envelope> 
       
Response  <RESULT>         
Elements  SUCCESS  TRUE if successful       
  ListId  The ID of the query that was created.       
Example  <envelope:Envelope xmlns="SilverpopApi:EngageService.ListMgmt.UserActions"
xmlns:envelope="http://schemas.xmlsoap.org/soap/envelope/">
<envelope:Header/>
<envelope:Body>
<RESULT>
<SUCCESS>TRUE</SUCCESS>
<ListId>7835478</ListId>
</RESULT>
</envelope:Body>
</envelope:Envelope> 
       

Calculate the Current Contacts for a Query

CalculateQuery

This interface supports programmatically calculating the number of contacts for a query. A data job is submitted to calculate the query and GetJobStatus must be used to determine whether the data job iscomplete. You may only call the Calculate Query data job for a particular query if you have not calculated the query size in the last 12 hours.

Below is the syntax for the API request and response:

Operation  <CalculateQuery>     
Elements  QUERY_ID  The ID of the Query to be calculated.   
  EMAIL  Optional  If specified, Watson Campaign Automation sends a notification email to the provided email address when the job is complete. 
Example  <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ses="SilverpopApi:EngageService.SessionHeader"
xmlns:user="SilverpopApi:EngageService.ListMgmt.UserActions">
<soapenv:Header>
<ses:sessionHeader>
<ses:sessionid>16FE7B75445E6C704707025B1B7BBEE5</ses:sessionid>
</ses:sessionHeader>
</soapenv:Header>
<soapenv:Body>
<user: CalculateQuery>
<user: QUERY_ID>59294</user: QUERY_ID>
<user:EMAIL>somebody@domain.com</user:EMAIL>
</user: CalculateQuery>
</soapenv:Body>
</soapenv:Envelope> 
   
Response  <RESULT>     
Elements  SUCCESS  TRUE if successful   
  JOB_ID  Identifies the Watson Campaign Automation Background Job created and scheduled for this export.   
Example  <envelope:Envelope xmlns="SilverpopApi:EngageService.ListMgmt.UserActions"
xmlns:envelope="http://schemas.xmlsoap.org/soap/envelope/">
<envelope:Header/>
<envelope:Body>
<RESULT>
<SUCCESS>TRUE</SUCCESS>
<JOB_ID>499600</JOB_ID>
</RESULT>
</envelope:Body>
</envelope:Envelope> 
   

Join The Discussion

Your email address will not be published. Required fields are marked *