Skip navigation

In the post Eloqua API How To: Create and Retrieve a Data Card, we looked at the basics of creating Data Cards.

 

Now that the new data card is created, you may wish to link it to a particular Contact record.  Let's take a look at how this can be accomplished.

 

When you created the Data Card, you created a Field/Value collection for the DynamicEntity, and then added email and title as fields in that collection:

 

// Create a Dynamic Entity's Field Value Collection
dynamicEntities[0].FieldValueCollection = new DynamicEntityFields();

dynamicEntities[0].FieldValueCollection.Add("Email1", "cloud_support@eloqua.com");

dynamicEntities[0].FieldValueCollection.Add("Title1", "Cloud");

 

To map this data card to a Contact, you will simply need to add a couple extra fields to the collection as follows:

dynamicEntities[0].FieldValueCollection.Add("MappedEntityType", "");

dynamicEntities[0].FieldValueCollection.Add("MappedEntityID", "");

 

For the MappedEntityType field, use either "1" for Contact (or "2" for Company).  For our example, let's map this card to a Contact record:

dynamicEntities[0].FieldValueCollection.Add("MappedEntityType", "1");

 

Now, for the MappedEntityID, you will need to have the ID for the Contact record that you wish to map to.  If you are creating a new contact record, and trying to map it to the Data Card right away, then just use the ContactID that you had returned to you when you created the contact (see Eloqua API How To: Create and Retrieve a Contact for more details):


var result = service.ServiceProxy.Create(dynamicEntities);

foreach (CreateResult t in result)
{
     // Successfull requests return a positive integer value for ID
     if (t.ID != -1)
     {
          contactId = t.ID;
          success = true;
     }

)


In this case, just use the ID that you stored in your variable contactID:

dynamicEntities[0].FieldValueCollection.Add("MappedEntityID", contactId.ToString());

 

If you want to use the ID of an already existing contact, then you'll have to retrieve the contact record first, then use the ID that you get back with the record.

SeeEloqua API How To: Query a Contact by Email Address or Eloqua API How To: Query a Contact by Multiple Fields for more details.

In our previous post, we introduced Eloqua's REST API with examples in .Net, Python, PHP, Ruby, Node.js, and Java These posts were meant to demonstrate how easy it is to work with a RESTful API. In today's post, we'll introduce some building blocks to help make things even easier.

 

All request libraries for Eloqua's API are now available on Github :

  1. eloqua-request : a Node.js repository for making requests to Eloqua's REST API
  2. eloqua-ruby-request : a Ruby repository for making requests to Eloqua's REST API
  3. eloqua-php-request : a PHP repository for making requests to Eloqua's REST API
  4. eloqua-python-request : a Python repository for making requests to Eloqua's REST API
  5. eloqua-csharp-samples : a repository of open source API samples in C#
  6. eloqua-csharp-client : a Rest client written in C# for Eloqua's API
  7. eloqua-java-request : a Rest client written in Java for Eloqua's API

 

If you're new to Github, you can find everything you need to get started here, including instructions on how to get the code. Please note that we're working on similar libraries in Ruby and C#, coming soon!

 

Let's look at how simple it is to make requests using these libraries.

 

Node.js

Using the Node.js request library :

var Eloqua = require('eloqua-request');
var eloqua = new Eloqua('site', 'user', 'pw', 'baseUrl');
eloqua.get('/API/REST/1.0assets/emails?search=Demand*&page=1&count=50&depth=minimal', function(err, response){
  ...
});

 

Ruby

Using the Ruby request library :

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

 

PHP

Using the PHP request library :

<?php
include('./eloquaRequest.php');
$eloquaRequest = new EloquaRequest('site', 'user', 'password', 'baseUrl');
$response = $eloquaRequest->get('/API/REST/1.0/assets/emails?search=Demand*&page=1&count=50&depth=minimal', $data);
...
?>

 

Python

Using the Python request library :

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

request = EloquaRequest('site', 'user', 'password')
response = request.get(url, None)

 

.NET

Using the C# rest client :

 

Create Client
var client = new Eloqua.Rest.Api.ClientLibrary.Client("site", "user", "pass"); 

 

GET (list)
List<Email> emails = client.Assets.Email.Get("searchTerm", pageNumber, pageSize);  


POST

Email email = new Email() { ... };  
email = client.Assets.Email.Post(Email);  


PUT

Email email = new Email() { ... };  
email = client.Assets.Email.Put(Email);  


DELETE

int emailId = 1;  
client.Assets.Email.Delete(emailId);  

 

We hope that you'll find these helpful.

 

Thanks,

Fred


In our last post we introduced Eloqua's REST API with a simple example using PHP. Given the popularity of Node.js - we wanted to do a similar introduction for the JavaScript community.

 

In this post, we'll walk through a simple example in Node.js to demonstrate how easy it is to work with Eloqua's REST API. The code sample invokes a GET request with basic authentication to retrieve a list of Emails from the Eloqua application. The use cases vary, but we’re essentially providing a hook for retrieving a list of data from Eloqua's API. We're sure you'll find some great and exciting ways to use this.

 

For now, let's get started with a simple request to Eloqua's REST API using Node.js

 

// Include the request library for Node.js
var request = require('request');

//  Basic Authentication credentials
var username = "Company\\Username";
var password = "xxxxx";
var authenticationHeader = "Basic " + new Buffer(username + ":" + password).toString("base64");

// Search for Emails with name containing Demand
request(
    {
        url : "https://secure.eloqua.com/API/REST/1.0/assets/emails?search=*Demand*&page=1&count=50&depth=minimal",
        headers : { "Authorization" : authenticationHeader }
    },
    function (error, response, body) {
        console.log(body);
    }
);

 

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 
} 

 

I hope this was a helpful introduction to the REST API and how easy it is to work with. We'll explore more of the REST API in future posts.

 

Thanks,

Fred

Eloqua will soon be exposing our web services in the form of REST Resources. Eloqua already provides a web services API, 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 PHP.

 

In this post, we'll walk through a simple example in PHP to demonstrate how easy it is to work with the REST API. The only prerequisites are PHP + cURL. The code sample invokes an HTTP GET request with basic authentication to retrieve a list of Emails from the Eloqua application. The use cases vary, but we’re essentially providing a hook for retrieving a list of Eloqua Emails and displaying their Content. In future posts, we’ll discuss how to manage the content and deliver the email using the REST API. For now, let's get started with a simple request to Eloqua's REST API :

 

First, you’ll need user credentials for the API

 

// Basic Auth API Credentials
$user = "CompanyName\User.Name";
$password = "xxxxxx";


 

Now let’s provide a function that given a URL endpoint will invoke an HTTP GET request decorated with basic HTTP authentication headers and returns the API response.

 

function get_request($user, $password, $url)
{
       // create the cURL resource
       $ch = curl_init();


       // set cURL options
       curl_setopt($ch, CURLOPT_URL, $url);


       // basic authentication
       curl_setopt($ch, CURLOPT_USERPWD, $user . ':' . $password);


       // execute request and retrieve the response
       $data = curl_exec($ch);


       // close resources and return the response
       curl_close($ch);


       return json_decode($data);
}


 

Now, let’s get some data...

 

// Search for Emails with name containing *Demand*
$emails = get_request($user, $password, "https://secure.eloqua.com/API/REST/1.0/assets/emails?search=*Demand*&page=1&count=50&depth=minimal");


 

And display the results

 

// Display the name and id of each email
foreach($emails['elements'] as $item)
{
       print ('Email:'. $item['name'] . $item['id']);
}


 

Invoke another get request to retrieve an individual Email

 

// Get an Email
$email = get_request($user, $password, "https://secure.eloqua.com/API/REST/1.0/assets/email/111?depth=complete");


 

Finally, let's output the body of the Email

 

// print the Body of the Email
print('Email HTML Body : ' . $email->htmlContent->htmlBody);


 

I hope this was a helpful introduction to the REST API and how easy it is to work with. We'll explore more of the REST API in future posts.

 

Thanks,

Fred