The Watson Campaign Automation XML API library provides an efficient mechanism to accomplish many automation and integration tasks.

See the Developer content for detailed information about API requests and responses as well as the Test Harness, or the Postman Collection, which includes IBM API Endpoints.

Feature

The XML API interface defines standard XML requests and responses for the following functions:

Session Management

IBM supports 2 types of authentication with API:

  • OAuth 2.0 Is our preferred method of session management due to its inherently increased security and implementation flexibility.
  • jSession is our legacy approach of session management. It is not recommend for any integration with Watson Campaign Automation to use these operations.

Automation

  • <GetProgramsByContact> (Get a contact’s relationship to programs) – used to extract a list of programs for a specific contact or visitor.
  • <GetPrograms> (Get a list of programs) – used to extract a list of Programs for an organization.

Database Management

Database Management interfaces allow you to invoke Watson Campaign Automation functions directly related to database contacts.

  • <AddRecipient> (Add a Contact) – used to add one new contact to an existing Watson Campaign Automation database.
  • <CalculateQuery> (Calculate the Current Contacts for a Query) – used to calculate the number of contacts for a Watson Campaign Automation query.
  • <CreateQuery> (Create a Query or Classic Query) – used to programmatically create a query of an Watson Campaign Automation database.
  • <DoubleOptInRecipient> (Double Opt-In a Contact) – used to confirm the Optā€in for a contact in a Watson Campaign Automation Double Optā€in Database.
  • <ExportList> (Export from a Database) – used to export contact data from a Watson Campaign Automation database, query, or contact list.
  • <GetLists> (Get a List of Databases) – used to extract a list of Watson Campaign Automation databases for an organization.
  • <GetListMetaData> (Get Database details) – used to return the description of a Watson Campaign Automation database, query, or Relational table.
  • <ImportList> (Import to a Database) – used along with SFTP to allow importing a batch file that contains new, modified, or opted out contacts. Contacts can also be added to an existing Watson Campaign Automation Contact list.
  • <OptOutRecipient> (Opt out a Contact) – used to move a contact in a Watson Campaign Automation database to an optedā€out state.
  • <Purge Data> (Purge Data) – used to delete all records from a Watson Campaign Automation database, suppression, seed, test or contact list (target) based on the contacts that exist in a specific database, contact list, or query (source).
  • <RemoveRecipient> (Remove a Contact) – used to remove a contact from a Watson Campaign Automation database or contact list. CAUTION: Removing a recipient from a database also removes all tracking for mailings sent to the recipient and cannot be undone.
  • <SelectRecipientData> (Select Contact Details) – used to retrieve information about a contact in a Watson Campaign Automation database.
  • <SetColumnValue> (Set a Column Value) – used to update a column value for all records in a Watson Campaign Automation Restricted database or a Watson Campaign Automation query.
  • <UpdateRecipient> (Update a Contact)  – used to update a contact in an existing Watson Campaign Automation database.

Contact List Management

Contact List Management interfaces allow you manage and leverage your recipient, prospect, and customer data.

  • <AddContactToContactList> (Add a Contact to a Contact List) – used to add one new contact to a Watson Campaign Automation Contact list.
  • <AddContactToProgram> (Add a Contact to a Program) – used to add a Contact to the beginning of a Watson Campaign Automation Program.
  • <CreateContactList> (Create a Contact List) – used to create a Watson Campaign Automation Contact list.
  • <GetContactMailingDetails> (Get Contact Mailing Details) – used to return details about a Watson Campaign Automation mailing sent to a specific contact.

Relational Table Management

A database that can be perceived as a set of tables and manipulated in accordance with the relational model of data. A Relational Table database contains indices that create a one to many relationship between data in one file and data in many other files.

  • <CreateTable> (Create a Relational Table) – used to create a Relational table in Watson Campaign Automation.
  • <DeleteRelationalTableData> (Delete Records from a Relational Table) – is used to delete records from a Watson Campaign Automation Relational table.
  • <DeleteTable> (Delete a Relational Table) – used to delete Watson Campaign Automation Relational table data.
  • <ExportTable> (Export from a Relational Table) – used to export Watson Campaign Automation Relational table data.
  • <ImportTable> (Import to a Relational Table) – used to create or update a Watson Campaign Automation Relational table.
  • <InsertUpdateRelationalTable> (Insert and Update Records in a Relational Table) – used to insert or update Watson Campaign Automation Relational table data.
  • <JoinTable> (Associate Relational Data with Contacts in a database) – used to associate a Watson Campaign Automation database with a Watson Campaign Automation Relational table.
  • <PurgeTable> (Purge Data from a Relational Table) – used to programmatically delete Watson Campaign Automation Relational table data.

Scoring Models

Watson Campaign Automation supports two great Program APIs, Get a list of scoring models and Get a contact’s scoring model scores, that allow discovery of Programs that are available to a specific database and also how an individual contact interacted with a program.

  • <GetContactScores> (Get a contact’s scoring model scores) – used to return the contact’s Watson Campaign Automation Scoring model’s values for a particular contact.
  • <GetScoringModels> (Get a list of scoring models) – used to get Watson Campaign Automation Scoring models for a specific organization.

Template and Mailing Management

Mailing Management interfaces allow you to invoke Watson Campaign Automation functions directly related to particular mailings.

  • <ExportMailingTemplate> (Export a Mailing Template) – used to export a Watson Campaign Automation mailing template.
  • <ForwardToFriend> (Forward Mailing to a Friend) – used to send a copy of a Watson Campaign Automation mailing along with an additional message to the specified contacts.
  • <GetMailingTemplates> (Get a List of Mailing Templates) – used to extract a list of Shared or Private Watson Campaign Automation mailing templates for your Organization.
  • <GetMessageGroupDetails> (Get Automated Message Group Details) – used to provide the description of an Watson Campaign Automation Automated Message Group.
  • <PreviewMailing> (Preview a Mailing Before Sending) – used to return a preview of a Watson Campaign Automation mailing template.
  • <SaveMailing> (Create or update a mailing template) – used to save a new or update an existing Watson Campaign Automation mailing template that can be used against a Watson Campaign Automation database, Contact list, or query.
  • <ScheduleMailing> (Schedule a Mailing) – used to send a Watson Campaign Automation templateā€based mailing to a specific Watson Campaign Automation database or query.
  • <SendMailing> (Send a Mailing to a Contact) – used to send a Watson Campaign Automation mailing to the specified contact. The SendMailing operation is specifically for the delivery of autoresponders based on a custom event.

Dynamic Content

HTML content on websites, forms, landing pages or email that changes frequently and engages the reader.

  • <AddDCRuleset> (Add a Dynamic Content Ruleset) – used to create a ruleset including its content areas, rules, and content.
  • <DeleteDCRuleset> (Delete a Dynamic Content Ruleset) – used to delete the specified ruleset from the Watson Campaign Automation Asset library.
  • <ExportDCRuleset> (Export a Dynamic Content Ruleset) – used to export the specified ruleset and all associated content, including images, from the Watson Campaign Automation Asset Library as a .zip file.
  • <GetDCRuleset> (Get Dynamic Content Ruleset Details) – used to return the specified ruleset in XML format.
  • <ImportDCRuleset> (Import a Dynamic Content Ruleset) – used to import a .zip containing the XML file defining a Watson Campaign Automation Dynamic Content ruleset and any associated HTML or images.
  • <ListDCRulesetsForMailing> (List Dynamic Content Rulesets for a Mailing) – used to return a list of available Watson Campaign Automation DC rulesets for the specified mailing.
  • <ReplaceDCRuleset> (Replace a Dynamic Content Ruleset) – used to replace an existing ruleset with newly specified parameters.
  • <ValidateDCRuleset> (Validate a Dynamic Content Ruleset) – used to perform a validation check against all Watson Campaign Automation Dynamic Content rulesets (including nested Rulesets) associated with the specified mailing.

Reporting

Watson Campaign Automation archives mailing tracking data after 450 days by default. You can modify this setting to reduce the number of days, but 450 is the maximum setting. For Autoresponders, if the SEND or ACTION date ranges specified are greater than 450 days (or the number of days that are configured for archiving), you receive an error message (returned from the call) specifying that the mailing was archived. If the date range spans both archived and available data for the mailing, the Watson Campaign Automation returns only the data available and does not return archived data.

If your Organization frequently requests data older than 30 – 60 days, leave the archive setting at 450 days. Try to refrain from requesting data older than one year to avoid including archived data in an export date range.

  • <ListRecipientMailings> (List Contact Mailings) – used to return a list of Watson Campaign Automation mailings for a specified database (or query) and contact as well as metrics associated with those mailings.
  • <GetReportIdByDate> (Get Report ID by Date) – used to extract the Report IDs for a particular Watson Campaign Automation mailing that is sent between specified dates.
  • <GetSentMailingsForOrg> (Get Sent Mailings for an Org) – used to extract a listing of Watson Campaign Automation mailings that are sent for an organization for a specified date range.
  • <GetSentMailingsForUser> (Get Sent Mailings for a User) – used to extract a listing of Watson Campaign Automation mailings that are sent for the logged on user for a specified date range.
  • <GetSentMailingsForList> (Get Sent Mailings for a database) – used to extract a listing of Watson Campaign Automation mailings that are sent for a particular database and specified date range.
  • <GetAggregateTrackingForMailing> (Get Aggregate Tracking Metrics for a Mailing) – used to extract metrics for a specified Watson Campaign Automation mailing.
  • <GetAggregateTrackingForOrg> (Get Aggregate Tracking Metrics for an Org) – used to extract a listing of Watson Campaign Automation mailings that are sent for an organization for a specified date range and provides metrics for those mailings.
  • <GetAggregateTrackingForUser> (Get Aggregate Tracking Metrics for a User) – used to extract a listing of Watson Campaign Automation mailings that are sent by a user for a specified date range and provides metrics for those mailings.
  • <RawRecipientDataExport> (Export Raw Contact Events) – used to export unique contact-level events and creates a compressed file that contains a single flat file with all metrics.
  • <WebTrackingDataExport> (Export Web Tracking Events) – used to export unique Watson Campaign Automation Web Tracking events and create a compressed file that contains a single flat file with all events.

Miscellaneous

  • <DeleteJob> (Delete a Data Job) – used to remove a job from Watson Campaign Automation.
  • <GetFolderPath> (Get Folder Path of a Folder or Object) – used to return the folder path for a specified folder ID or a specified Object ID (for example, database, Query, Contact List, or Mailing).
  • <GetJobStatus> (Get Status of a Data Job) – used to monitor the status of a job after the data job is initiated.

5 comments on"API Reference Guide"

  1. Hello Naga,
    What exactly do you need more information about? the API Reference Guide? Can you give me more info?

    Thank you
    Jeri

  2. Krishna Sarigopula November 09, 2018

    I am unable to find calling way to though XML API Search for Contact or Get All contacts from contact list

    • Hello Krishna,
      Are you wanting to extract contact information from a list and not the list itself?

      Thank you
      Jeri

  3. Hello,

    Is it possible to delete contacts through the api and to add contacts through querying the parent database?

    • Hello Vincent,
      (Purge Data) ā€“ used to delete all records from a Watson Campaign Automation database, suppression, seed, test or contact list (target) based on the contacts that exist in a specific database, contact list, or query (source).

      Thank you
      Jeri

Join The Discussion

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