Overview

Skill Level: Intermediate

Prerequisites

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

When adding/updating records in your organization‚Äôs CRM List, you can specify whether to sync the contact to your CRM system by passing a COLUMN element with a NAME ‚ÄúCRM Enable Sync‚ÄĚ and VALUE of Yes or No. If you do not include this column, the organization‚Äôs default setting will be used.

When adding/updating records in your organization‚Äôs CRM List, you can specify whether the individual is a Lead or Contact by passing a COLUMN element with a NAME ‚ÄúCRM Contact Type‚ÄĚ and VALUE of ‚ÄúLead‚ÄĚ or ‚ÄúOther‚ÄĚ. If you do not include this column, the individual will be designated a Lead.

Step-by-step

  1. Syntax of the request and response XML for AddRecipient

    Operation AddRecipient      
    Elements LIST_ID The ID of the database to which you are adding the contact.   
      CREATED_FROM

    Value indicating the way in which you are adding the contact to the system. Values include:

    0 ‚Äď Imported from a database

    1 ‚Äď Added manually


    2 ‚Äď Opted in


    3 ‚Äď Created from tracking database

     

     
      SEND_AUTOREPLY  Optional If the database has an autoresponder associated with it and the SEND_AUTOREPLY element is set to true, Engage sends the confirmation when the contact is added to the database.  
      UPDATE_IF_FOUND Optional If the UPDATE_IF_FOUND element is set to true, attempting to add a contact with a duplicate key will result in an update to their record. If the database has no Unique Identifier and UPDATE_IF_FOUND is set to true, attempting to add a contact with duplicate SYNC_FIELDS will result in an update to the record.  
    ¬† ALLOW_HTML Optional If ALLOW_HTML is set to true, Engage will interpret‚ÄĒand properly render‚ÄĒHTML within a value in the text field. The default value is false and will convert HTML tags to character entity references (and tags display as literal characters in the text field).¬† ¬†
      VISITOR_KEY Optional Allows specifying a visitor key to associate a contact to a previously unknown visitor when using the Wrb Tracking feature.  
      CONTACT_LISTS  Optional If included, the contact will be added to all specified contact lists in addition to a database.  
        Child Element  CONTACT_LIST_ID The contact list id that contact will be added to.
      SYNC_FIELDS Optional Required if the database has no Unique Identifier and UPDATE_IF_FOUND is set to true. 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, the oldest contact will be updated. Sync fields will be ignored if the database has a key.  
      Child Element  SYNC_FIELD XML nodes defining the column name and value of the unique identifier fields. Each node must have a Name tag and a Value tag.  
        Child Element NAME Defines the field name.
          VALUE  Defines the field value.
        COLUMN  XML nodes defining the column name and value for fields being added or updated. Note: Each node must have a Name tag and a Value tag. If the database has a key that is not Email, Unique key columns must also be part of the submission with column names and values.   
        Child Element  Name  Defines the field name. The name of the Email column must be EMAIL. The name of the email type column must be EMAIL_TYPE
          Value  Contains the field value.
    Example with contact list ids 

    <Envelope>
        <Body>
            <AddRecipient>
               <LIST_ID>85628</LIST_ID>
               <CREATED_FROM>1</CREATED_FROM>
               <CONTACT_LISTS>
                   <CONTACT_LIST_ID>289032</CONTACT_LIST_ID>
                   <CONTACT_LIST_ID>12345</CONTACT_LIST_ID>
               </CONTACT_LISTS>
               <COLUMN>
                   <NAME>CustomerId</NAME>
                   <VALUE>123-45-6789</VALUE>
               </COLUMN>
               <COLUMN>
                   <NAME>EMAIL</NAME>
                   <VALUE>somebody@domain.com</VALUE>
               </COLUMN>
               <COLUMN>
                   <NAME>Fname</NAME>
                   <VALUE>John</VALUE>
               </COLUMN>
             </AddRecipient>
           </Body>
    </Envelope>

       

    Example 2 with Sync Fields 

    <Envelope>
        <Body>
           <AddRecipient>
               <LIST_ID>85628</LIST_ID>
               <CREATED_FROM>2</CREATED_FROM>
               <SYNC_FIELDS>
                  <SYNC_FIELD>
                     <NAME>EMAIL</NAME>
                     <VALUE>somebody@domain.com</VALUE>
                  </SYNC_FIELD>
                  <SYNC_FIELD>
                     <NAME>CustomerId</NAME>
                     <VALUE>123-45-6789</VALUE>
                  </SYNC_FIELD>
            </SYNC_FIELDS>
            <COLUMN>
               <NAME>Street_Address</NAME>
               <VALUE>123NewStreet</VALUE>
            </COLUMN>
         </AddRecipient>
    </Body></Envelope>

       

    Response  <RESULT>      
    Elements  SUCCESS True if successful    
      RecipientId  ID of added or updated contact.     
      ORGANIZATION_ID Identifies your Watson Campaign Organization     
      VISITOR_ASSOCIATION  Optional  Indicates whether the specified Visitor ID is valid and was associated to a profile.  
    Example  <Envelope>
        <Body>
            <RESULT>
                <SUCCESS>TRUE</SUCCESS>
                <RecipientId>33535067</RecipientId>
            </RESULT>
         </Body>
    </Envelope> 
       

5 comments on"Add a Contact"

  1. Say I’ve added a contact to a database on day 1 using AddRecipient. On day 2, I need to add that contact to 1 or more contact lists.
    Is there any reason not to use AddRecipient again, with true, to add the contact to the contact lists — instead of having to issue a SelectRecipientData first to get their Recipient_ID in order to then issue an AddContactToContactList call? The latter seems cumbersome…

    Thanks.

    • Hi Tom,
      I’m looking into this and I’ll get back to you when I have more info.

      Thank you
      Jeri

  2. jesus ca√Īedo April 16, 2019

    is there a way to import more than one contact without the instrucction in order to avoid the upload files ? if add multiple nodes, does this will work?

  3. Can be used to add an email address to the Master Suppression List? If not, is there a way to do this with the XML API? If not, what API (and command) do you recommend?

Join The Discussion

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