Eloqua: Get data via Eloqua REST API

You can leverage ion’s Get Lead integration with the Eloqua REST API to optimize your ion experiences. This integration enables you to retrieve data from Eloqua based on a respondent's email address. You can leverage Get Lead to pre-populate (or shorten) ion forms, auto-segment respondents and for progressive profiling.

This document provides step-by-step instructions to set up a REST API integration with Eloqua to get lead data. We’ll use the integration to pre-populate an ion form in this document, but, as noted, there are a few different ways you can use Get Lead to enhance your ion experiences.

Before we begin

There are few items you'll need to a roundup from Eloqua prior to setting up the integration, listed below:

  • Eloqua Username
  • Eloqua Password
  • REST API Endpoint URL

There are few items you'll need to have ready in ion prior to setting up the integration, listed below:

Check out the "Before you begin" support post for guidance in creating these items.

  • Create data collection fields that will store Eloqua data
  • Create ion form(s) that will populate with Eloqua data
    • You can pass an email address value into the ion page on the query string, and populate a form on the landing page with data
    • OR, you can collect email address on an initial form, and populate a subsequent form with Eloqua data
  • Set up testing creative

Let’s Get Started!

1. Add Eloqua account credentials to ion

  1. Click the Integrations tab in your console’s side nav
  2. Click “Set up account credentials” button
  3. Under Eloqua, click the “New eloqua credential” button
  4. Add a friendly label for your account then click "authorize eloqua"
  5. Add your Eloqua credentials into the embedded Eloqua interface and then click "Accept" to allow ion to access the Eloqua REST API

2. Create field mapping

Taking the steps below will enable you to extend an email address value to Eloqua and map the data points returned to their corresponding ion data collection fields. To get started, add your new field mapping:

  1. Navigate back to the Integrations screen
  2. Click green “New field mapping” button
  3. Label the field mapping and optionally add a description
  4. From the Integration type menu, select “Eloqua”
  5. Save

3. Add Email Address as the Outbound field

The email address value will be used as the key to retrieve data from Eloqua.

  1. Click green “New outbound field” button
  2. Select Data field from the Source drop-down
  3. Select Contact Info > Email Address
  4. Make the field required for the integration to run
  5. Select the corresponding Eloqua Email Address field
  6. Save

4. Create Inbound fields

Inbound fields will map the data Eloqua returns into their corresponding ion data collection fields.

  1. Click green “New inbound field” button
  2. From the Target dropdown menu, select Data field and then select the ion data field you seek to populate with Eloqua data
    • To pre-populate ion forms with Eloqua data, be sure to select the data field used on your form
  3. From the Source dropdowns, select the Eloqua field you seek to pull data from
  4. OR, select Javascript code if you seek to transform the Eloqua data prior to storing it in ion data collection
    • Use responseBody.eloqua_field_name to access the Eloqua field via Javascript
  5. OR, select Response body to save the response from Eloqua to an ion data field
  6. Save
  7. Repeat these steps for each Eloqua data field you seek to save into ion data collection

5. Create integration

  1. Navigate back to the Integrations screen
  2. Click into the Integrations tab
  3. Click green “New integration” button
  4. Enter label
  5. Optionally add a description
  6. Select the Field Mapping you’ve just created
  7. Skip Maximum retries
  8. Select Get Lead as the API method
  9. Select the outbound Email Address field
  10. Optionally add yourself to the debug distribution list for testing
    • This will deliver an email to the designated address when the integration runs that displays the request and response from Eloqua
    • Check Only send error emails if you want to receive the debug email only when there is an error

6. Add integration to ion pages

The ion platform runs the integration based on rules you create. For Eloqua Get Lead, the rule will typically run behind a form that collects email address (so that the Eloqua data is available for use on the subsequent page), or the rule is run at the page-level of a landing page where email address is passed in on the query string.

  1. Navigate into a testing creative
  2. If passing email address into your page from the query string, under the Page tab in creative studio, click on +RULES
  3. Add the following rule:
    • Condition: No conditions required
    • Action: Run integration (select Elq Get Lead integration)
    • OR, if collecting email address on an initial form, run the above rule at the form-level
  4. Save

7. Test integration

Please note, integrations do not run in Preview Mode, so you'll want to open a URL for your testing creative. Either pass email address into your ion page on the query string, or submit your initial form that collects email address. If passing email address into ion on the query string, be sure that the parameter name you append to the URL matches the "data name" of the ion data collection field selected as the outbound field in your Field Mapping.

Once the integration runs, the form you seek to pre-populate will display the data retrieved from Eloqua. If you’re on the debug email distribution list, you’ll receive an email that displays the request and response from Eloqua.

Nice work!

Once you’ve completed these steps, your integration is ready for use. You can add the rule to run the integration on all applicable creatives.

As noted, Eloqua Get Lead can be used to accomplish other objectives. Here are some examples that can be accomplished using this integration and ion's Rules engine:

  • Shorten or replace forms
  • Auto-segment respondents
  • Build progressive profiles
  • Serve-up dynamic content based on Eloqua data