DIY Integrations: Getting Contacts Into Your Account With Direct Add that explained how to use Direct Add. With the Spring 2010 release, we have moved this feature to a new location and made some improvements to it. This post will walk you through how to use Direct Add and where to find it in the application.

Obtain the URL

In order to begin using Direct Add, you need to enable the feature and obtain the Direct Add URL. To do this:
  1. Go to Home->Settings->Data Exchange.
  2. Scroll to the Direct Add section and click the Enable Direct Add for adding new contacts checkbox.

Understand the URL

The Direct Add URL works by you specifying parameters that correspond to a contact to add, fields and data you want to associate the contact with, and lists you want to add the contact to. We will be adding these parameters to the image URL in the following format: &email=email@example.com&field1=field,operation,value&list2=listid. For example:
http://example.com/public/?q=direct_add&fn=Public_DirectAddForm&id=IDSTRING&email=email@example.com&field1=lifetimevalue,set,129.23&list2=555555ec0000000000000000000000055f5&field3=age,set,24&list4=33333ec000000000000000000000003f3
The first part of the URL is given to you as part of the code snippet you got from the Direct Add section on the Data Exchange page. This is unique to each account and allows the application to identify your account. The next few parameters, q, fn, and id allow us to know how to process the data that is to follow, as well as identify your account. The last bit, is the actual string that we created earlier.
&email=email@example.com&field1=lifetimevalue,set,129.23&list2=555555ec0000000000000000000000055f5&field3=age,set,24&list4=33333ec000000000000000000000003f3

Construct The URL

At a really high level, Direct Add works by specifying a contact that you want to add, field data that you want to include for the contact, and a list you want to add the contact to. This is accomplished by adding parameters to a URL contained in an image tag in the following format: &email=example@example.com&field1=fieldname,operation,value&list2=listid. Notice that for fields, you specify the field name, followed by set, and then a specific data value. For lists, you only need the list ID.

Fields

In order to specify a field to add, you will need to use the exact spelling of that field as you specified it within the application. You can see a listing of all your contact fields by going to Contacts->Fields. Because you are adding a new contact, you will only be able to use set as the operator when adding field data. Note - set adds a value to the specified field. Field types supported: number, decimal, currency, date, text, text area, checkbox, radio button, and pull-down. Also, be sure to use only lower case letters for the operators.

Lists

In order to specify a list to add the contact to, you will need to make note of the id that corresponds to the specific list. For any list, you can go to Contacts->Lists and click on the name of the list you want to use. On the Overview page for that list, you will see an id number for the list. Make note of the list id, as it will be used in the Direct Add URL.

Multiple Adds

You can add more than one field and or list at a time. The application supports adding up to 10 parameters (fields, lists, or a combination of both) within one call. Additional fields and lists are included by adding another value parameter to the image URL. Multiple fields and lists are separated by the ampersand character (&). You also need to increment the number after each field or list. For example:
field1=lifetimevalue,set,129.23&list2=555555ec0000000000000000000000055f5&field2=age,set,27&list4=33333ec0000000000000000000000033f3

Setting Up The Direct Add Image Tag And Adding It To Your Site

Once you have a clear understanding of how the Direct Add URL works, you can begin setting up Direct Add.

To setup Direct Add:

  1. Go to Home->Settings->Data Exchange.
  2. Click the Enable Direct Add for adding new contacts checkbox.
  3. (Optional) Click the Add contacts with "unconfirmed" status. (By default all contacts are added with "active" status) checkbox to give contacts added via Direct Add a status of unconfirmed. This setting only applies to contacts being added via Direct Add and does not apply to contacts being added to the application by other means (manual creation, import, etc.).
  4. (Optional) Click the Send a welcome message checkbox to send a welcome message. If you choose to send a welcome message, you will need to do the following:
    1. Choose to have the welcome message sent:
      • Only when the contact being added is new.
      • Every time the Direct Add URL is used.
    2. Choose the welcome message to send using the message picker.
    3. Specify a From Name for the welcome message.
    4. Specify the From Address for the welcome message.
  5. Add the Direct Add img tag to a page on your site.
  6. Add any field and list parameters onto the URL that you want to pass back to the application. The email parameter is included on the Direct Add URL be default.
  7. Add values to the email, field, and list parameters. There are a number of ways you can accomplish this, with the most common being using javascript. The example below is of a page displayed to a website visitor after they have filled out a form requesting to receive email messages from the website. The page contains a message confirming the data the person provided/selected (the example below assumes they entered in their first name, last name, and email address and selected a message preference). The page also contains the Direct Add img tag, and some javascript that populates the Direct Add URL with the appropriate data.
    You may need to to scroll to the right to see the entire code example below:
    <html> <body>  <p>    Dear <span id="firstname">Joe</span> <span id="lastname">Example</span>,  </p>  <p>    Thank you for signing up to receive messages from Example Shop. We will be sending:  </p>  <p>    <span id="msgpref">HTML</span> messages to <span  id="email">joe@example.com</span>  </p> <script type="text/javascript">  // The following variables need to be set to some value that is  // available on the page, passed in, etc. Where you get these  // values will be different for each client's web site. Someone  // who is familiar with the client's web site will have to provide  // the values based on the type of page (order confirmation,  // receipt, etc.) shown to users after a form has been filled out.                 var firstname = document.getElementById('firstname').innerHTML;                 var lastname = document.getElementById('lastname').innerHTML;   var email = document.getElementById('email').innerHTML;   var msgpref = document.getElementById('msgpref').innerHTML;  // Note the incrementing number for the field and list parameters  // (field1....field2.....list3.....field4) etc.  // Make sure you get the proper Direct Add img tag from the  // Data Exchange page in your account. The img tag below uses  // a generic img tag.   document.writeln('<img src="http://app.example.com.com/public/?q=direct_add&fn=Public_DirectAddForm&id=blkycggbjquivddbiddxylaufhfdbkj&email='+email+'&field1=firstname,set,'+firstname+'&field2=lastname,set,'+lastname+'&field3=msgpref,set,'+msgpref+'&list4=33333ec000000000000000000000003f3" width="0" height="0" border="0" alt=""/>'); </script> </body> </html>

Finishing Up

This was a lot of information to cover, but hopefully you now have a good idea of how Direct Add works and how you can use it to add contacts to your account. If you have any questions, feel free to leave them in the comments section below.