API reference
Help CenterCommunityDevelopersAcademyStatus

Add a contact - AddRecipient

Adds one new contact to an existing Acoustic Campaign database.

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”, “Contact”, or “Other”. If you do not include this column, the individual will be designated a Lead.

Elements (Required)

LIST_ID - The database ID.

CREATED_FROM - The value indicating how you are adding the contact to the system: Imported from a database (0), Added manually (1), Opted-in (2), Created from a tracking database (3)

Elements (Optional)

SEND_AUTOREPLY - Engage sends a confirmation when a contact is added to the database if it has an associated auto-responder, and the SEND_AUTOREPLY element is set to true.

UPDATE_IF_FOUND - If set to true, adding a contact with a duplicate key results in an update to their record. If the database has no Unique Identifier and UPDATE_IF_FOUND is set to true, adding a contact with duplicate SYNC_FIELDS results in an update to the record.

ALLOW_HTML - If set to true, Engage interprets and properly renders HTML within the text field. The default value is false and converts HTML tags to character entity references and tags display as literal characters in the text field.

VISITOR_KEY - Specifies a visitor key to associate a contact with a previously unknown visitor when using the Web Tracking feature.

CONTACT_LISTS - If included, the contact is added to all specified contact lists as well as a database.
CONTACT_LIST_ID - The contact list ID that a contact is added.

SYNC_FIELDS - 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.
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.

  • 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.

  • 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. 
<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>[email protected]</VALUE>
           </COLUMN>
           <COLUMN>
               <NAME>Fname</NAME>
               <VALUE>John</VALUE>
           </COLUMN>
         </AddRecipient>
       </Body>
</Envelope>

<Envelope>
    <Body>
       <AddRecipient>
           <LIST_ID>85628</LIST_ID>
           <CREATED_FROM>2</CREATED_FROM>
           <SYNC_FIELDS>
              <SYNC_FIELD>
                 <NAME>EMAIL</NAME>
                 <VALUE>[email protected]</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>

<Envelope>
    <Body>
        <RESULT>
            <SUCCESS>TRUE</SUCCESS>
            <RecipientId>33535067</RecipientId>
        </RESULT>
     </Body>
</Envelope>

Elements (Results)

SUCCESS - True if successful; False if not.

RECIPIENTID - ID of added or updated contacts.

ORGANIZATION_ID - Identifies your Acoustic Campaign Organization

VISITOR_ASSOCIATION - Indicates whether the specified visitor ID is valid and associated to a profile. Note: This is optional.


📘

Note:

Incorrect column names will generate a contact without the information from that incorrect field/value.

<Envelope>
  <Body>
    <AddRecipient>
      <LIST_ID>17227248</LIST_ID>
      <CREATED_FROM>1</CREATED_FROM>
      <UPDATE_IF_FOUND>false</UPDATE_IF_FOUND>
      <COLUMN>
        <NAME>Emails</NAME>
        <VALUE>[email protected]</VALUE>
      </COLUMN>
    </AddRecipient>
  </Body>
</Envelope>

<Envelope>
    <Body>
        <RESULT>
            <SUCCESS>TRUE</SUCCESS>
            <RecipientId>1054387890708</RecipientId>
            <ORGANIZATION_ID>3e87da39-143d61bb907-37c504b367ce64f028215bda5330c1de</ORGANIZATION_ID>
        </RESULT>
    </Body>
</Envelope>