Skip navigation

I am asked the question in the title all the time, and the answer is actually pretty simple...

 

When building an application that integrates with Eloqua, the choice of where to host it is entirely up to you, but it must be somewhere external to Eloqua.

 

After I give that answer, the next question usually involves, "then what is cloudconnectors.eloqua.com?  Isn't that where Eloqua hosts the app for us?"

 

In order to clarify things, let me answer those two questions...

 

What is cloudconnectors.eloqua.com?

Quite simply, this is the site where the Eloqua labs team hosts apps that were developed in-house.  It resides outside of Eloqua, and a separate login is required to access apps on the site.

 

Isn't that where Eloqua hosts the app for us?

The answer here is no, Eloqua does not host externally developed apps.

 

Again, the choice of *where* is totally up to you, but some choices could be your company servers, or a cloud computing platform such as Windows Azure, Amazon Web Services, or Heroku.

fsakr

Eloqua REST API - HTTP Verbs

Posted by fsakr Aug 31, 2012

Eloqua's REST service supports four different verbs : Get, Post, Put and Delete. In today's post, we'll briefly describe each verb and provide examples of usage.

 

GET

Get is used to retrieve a representation or API entity from a resource. Can be used to retrieve one or more entities.

Examples :

The following request will retrieve a single entity (Email) with ID = 123

 

The following request will retrieve a list of entities (Email) containing the word : "Demand*"

 

POST

Post is used to create a new resource.

Example :

The following request will create a new entity (Email) from the body of the request

 

PUT

Put is used to update a resource.

Example :

The following request will update an existing entity (Email with identifier 123) from the body of the request

 

DELETE

Delete is used to delete a resource.

Example :

The following request will delete an entity (Email with identifier 123) from the body of the request

 

So, we've Authenticated, and learned about HTTP Verbs, next we look at Eloqua REST API - URL Parameters

 

We hope that you find this helpful.

 

Thanks,

Fred

Eloqua will soon be exposing our web services in the form of REST Resources. Eloqua already provides a Connecting to the Eloqua API - Generic Setup, well suited for integrated development environments like Eclipse and Visual Studio. These IDEs provide toolkits that can generate service proxies, making web services easy to use. The problem is that web services can be a challenge to work with when we don't have these proxies. REST APIs offer a lightweight alternative to web services and are easy to use with languages like Ruby and Python.

 

In this post, we'll introduce a request library written in Python that we're opening up to the community. The code is publicly available on Github at : fredsakr/eloqua-python-request · GitHub

The library supports the following operations :

  • GET
  • PUT
  • POST
  • DELETE

 

Let's look at a simple request using this library to search for Emails containing the word "Demand" :

 

We'll start by importing the library :

import sys
sys.path.append('./lib')
from eloqua_request import EloquaRequest

 

Next, we'll invoke a GET request to search for the Emails :

 

request = EloquaRequest('site', 'user', 'password')
response = request.get('/assets/emails?search=Demand*&page=1&count=50&depth=minimal', None)

 

The response for this call looks as follows :

 

{
  "elements": [
    {
      "type": "Email",
      "currentStatus": "Draft",
      "id": "86013",
      "createdAt": "1370981173",
      "createdBy": "9",
      "depth": "minimal",
      "folderId": "1422",
      "name": "Demand.html",
      "permissions": "fullControl",
      "updatedAt": "1370981173",
      "updatedBy": "9",
      "htmlContent": {
        "type": "RawHtmlContent",
        "contentSource": "upload"
      }
    },
    {
      "type": "Email",
      "currentStatus": "Draft",
      "id": "69830",
      "createdAt": "1362380717",
      "createdBy": "244",
      "depth": "minimal",
      "folderId": "1422",
      "name": "Demand Sample",
      "permissions": "fullControl",
      "updatedAt": "1362380784",
      "updatedBy": "244",
      "htmlContent": {
        "type": "RawHtmlContent",
        "contentSource": "upload"
      }
    },
   ...
  ],
  "page": 1,
  "pageSize": 10,
  "total": 130
}

 

Please note that the REST API is not yet public and the code samples available here are my own work. I'll be glad to help support and fix issues in the code, but please understand that Eloqua will not be able to support this - as it is my own.

 

Thanks,
Fred

As outlined in the post Building Cloud Connectors: Polling, a Cloud Connector is an application that, using the Eloqua APIs "polls" an Eloqua Campain Canvas or Program Builder Step for members.  It then performs an action on those members, and sets the member status to move it onto the next step.

 

The basic flow for a Cloud Connector app is as follows:

 

  1. Cloud Connector app "polls" the Campaign Canvas or Program Builder Step, and retrieves a count of members with a status of "Awaiting Action" - (see Cloud Connector API - Counting the Members in a Program Step)
  2. Once the step members have been counted, the app then makes a call to retrieve them (see Cloud Connector API - Retrieving IDs of Members in Program Builder Step) and mark them as "In Progress".  This ensures that other instances of the same Cloud Connector, or other threads that are operating at the same time, do not retrieve the same members more than once.
  3. The app then performs an operation on the member (for example, reaches out an external system and pulls data back into the contact record), and when completed, marks the record with a status of "Completed" (see post in Step 2).
  4. Program Builder or Campaign Canvas then sees the status has changed to "Completed" and moves the members on to the next step in the program.

 

For counting members in a step, retrieving them, and setting their status, you will need to use the ExternalActionService.

 

For updating contacts, companies, or custom data objects, you will need to use the EloquaService.

In previous posts, we introduced libraries in PHP, Node.js and C# for working with the REST API. Today, we’re going to start a library in Ruby. The library is available on github and is open to the community. Please note this is a work in progress and the goal is to have the community contribute to and help evolve the project.


Let's get started with a simple request to the REST API using Ruby.


require 'net/https'

https = Net::HTTP.new('secure.eloqua.com', 443)
https.use_ssl = true
https.verify_mode = OpenSSL::SSL::VERIFY_PEER

request = Net::HTTP::Get.new('/API/REST/1.0/assets/emails?search=*Demand*&page=1&count=50&depth=minimal')
request.basic_auth 'site\user', 'password'

response = https.request(request)



Now, let's look at the same request using the library.


require('eloqua-ruby-request')
eloquaRequest = EloquaRequest.new('site', 'user', 'password')
response = eloquaRequest.get('/assets/emails?search=Demand*&page=1&count=50&depth=minimal')



The response for this call looks as follows :

  {  
 "elements": [  
        {  
 "type": "Email", 
 "currentStatus": "Draft",  
 "id": "86013", 
 "createdAt": "1370981173",  
 "createdBy": "9", 
 "depth": "minimal", 
 "folderId": "1422", 
 "name": "Demand.html",  
 "permissions": "fullControl",  
 "updatedAt": "1370981173",  
 "updatedBy": "9", 
 "htmlContent": {  
 "type": "RawHtmlContent",  
 "contentSource": "upload"  
          }  
        },  
        {  
 "type": "Email", 
 "currentStatus": "Draft",  
 "id": "69830", 
 "createdAt": "1362380717",  
 "createdBy": "244", 
 "depth": "minimal", 
 "folderId": "1422", 
          "name": "Demand Sample",  
 "permissions": "fullControl",  
 "updatedAt": "1362380784",  
 "updatedBy": "244", 
 "htmlContent": {  
 "type": "RawHtmlContent",  
 "contentSource": "upload"  
          }  
        },  
       ...  
      ],  
 "page": 1,  
 "pageSize": 10,  
 "total": 130  
}  


Please note that the REST API is not yet public and the code samples available here are my own work. I'll be glad to help support and fix issues in the code, but please understand that Eloqua will not be able to support this.

 

Thanks,
Fred

We recently added support for searching a List or Group for Contacts. If you're not familiar with the C# Client, you can learn more about it here.

In today's post, we'll show you how to search for Contacts in a List.

 

Let's start by instantiating a new instance of the client and searching for a contact list :

 

Client client = new Eloqua.Api.Rest.ClientLibrary.Client("site", "user", "password");
ContactList list = client.Assets.ContactList.Get("*", 1, 100);

 

We'll assume that you're going to be searching for contacts in a List with ID : 1

And invoke a request to search the list for all contacts with the domain : @domain.com

 

int? listId = 1;

var result = client.Assets.ContactListMember.Get(listId, "*@domain.com", 1, 100);

 

We hope that you find this helpful.

Please note that the REST API is not yet public and the code samples available here are my own work. I'll be glad to help support and fix issues in the code, but please understand that Eloqua will not be able to support this - as it is my own.

 

Thanks,
Fred

In order to get started building applications on the Eloqua platform, you will first need to do some prep work.

 

1.  Join Eloqua’s Technology Partner Program

Fill in the form located HERE.  Once you are a signed partner, you will be given access to a development instance of Eloqua.

Note:  If you already have an instance of Eloqua to work with, make sure your account has API access (speak with your Eloqua Administrator to have this set up)

2.  Review the Resources available

A great starting point is Building On The Eloqua Platform - A Resource Guide, where you will find plenty of How-Tos and code snippets to get you going.  Also check the "How" area of Code It regularly for the latest posts.

3.  Check Out What Others Have Built

Visit the Eloqua Appcloud to see what is currently available for use by Eloqua customers.

4.  Discuss Your Experiences and Ask Questions

Participate in current discussions, and pose questions to the Eloqua Development Community.

In today's post we're going to share a Campaign helper project and demonstrate how to search for and retrieve Campaigns using the API.

The complete source for the project is available here on Github.

 

Let's start by creating a new instance of the CampaignHelper :

 

CampaignHelper campaignHelper = new CampaignHelper("site", "user", "password", "https://secure.eloqua.com/API/REST/1.0/");



 

Retrieving a Campaign by ID

If you know the ID of a Campaign in Eloqua, you can retrieve it using the following operation :

 

const int campaignId = 1;
Campaign campaign = campaignHelper.GetCampaign(campaignId);



 

The model for the campaign record is available here.

 

Searching for a Campaign by Name

If you want to search for a Campaign by name, you can use the following operation :

 

IRestResponse response = campaignHelper.GetCampaign("*", 1, 100);



 

Searching for a Campaign by CRM ID

If you know the ID of your Campaign in the CRM system, you can search for it using the following operation :

 

IRestResponse response = _campaignHelper.GetCampaign("crmId='70170000000Se4h'", 1, 1);



 

Please note that the samples referenced here are my own work and something that I've put together to try and help. I'll do my best to support it, but please understand that this code is not supported by Eloqua.

 

Thanks,

Fred