Skip navigation

We recently added an open source PHP Rest Client to help make requests to Eloqua's API a little easier. In today's post, we'll show you how to create and manage Landing Pages using the client.

Let's start by including and instantiating a new instance of the client :

 

// include the Rest client
include_once('lib/eloquaRequest.php');
$client = new EloquaRequest('site', 'user', 'password', 'https://secure.eloqua.com/API/REST/1.0/');

 

Next, let's define a class to represent a Landing Page record :

 

class LandingPage
    {
        public $createdAt;
        public $createdBy;
        public $htmlContent;
        public $id;
        public $name;
        public $updatedAt;
        public $updatedBy;
    }

 

Note that the HTML Content property is a complex type, represented by the following class :

 

class RawHtmlContent
    {
        public $type;
        public $html;
    }

 

Search Landing Pages

The following sample invokes a GET request to search for Landing Pages matching "Demand*" :

 

$list = $client->get('assets/landingPages?search=Demand*&count=50&page=1&depth=complete');

 

Create a Landing Page

The following sample creates a new Landing Page object and invokes an HTTP POST request to create the record :

 

$lp = new LandingPage();
$lp->name = 'sample landing page';
$htmlContent = new RawHtmlContent();
$htmlContent->html = '<html><head></head><body>sample content</body></html>';
$lp->htmlContent = $htmlContent;
$response = $client->post('assets/landingPage', $lp);

 

Update a Landing Page

The following sample invokes an HTTP PUT request to update an existing Landing Page.

 

$updatedLP = new LandingPage();
$updatedLP->id = $response->id;
$updatedLP->name = 'updated sample name';
$updatedLP = $client->put('/assets/landingPage/' . $updatedLP->id, $updatedLP);

 

Delete a Landing Page

The following sample invokes an HTTP DELETE request to delete an existing Landing Page

 

$client->delete('/assets/landingPage/' . $updatedLP->id);

 

We hope that you find this helpful.

 

Thanks,

Fred

fsakr

Eloqua REST API - User Access

Posted by fsakr Oct 20, 2012

In a previous post, we introduced the Rest API with an overview of Email management and deployment. In today's post, we'll introduce the User record.

 

URL : GET /system/user/{id}?depth={depth}

 

public class User
    {
        public List<string> betaAccess { get; set; }
        public List<string> capabilities { get; set; }
        public int? defaultContactViewId { get; set; }
        public string emailAddress { get; set; }
        public int? id { get; set; }
        public string loginName { get; set; }
        public string name { get; set; }
        public List<ProductPermission> productPermissions { get; set; }
        public List<TypePermissions> typePermissions { get; set; }
}
  

 

The user record contains information such as the beta access flags that are enabled as well as the areas of the application the user can access.

The sample project contains methods for retrieving a user and searching for lists of users. Note that a user create operation is not yet supported in the API.

 

A new open source project containing samples and helper methods for working with the user object is available here on Github.

Let's look at a sample json representation of the user object :

 

"type": "User",
      "id": "9",
      "createdAt": "1260902519",
      "createdBy": "8",
      "depth": "complete",
      "description": "John Smith",
      "name": "John Smith",
      "updatedAt": "1350572309",
      "updatedBy": "9",
      "betaAccess": [    
        "archiving_campaigns",
        "chatter_inside",
],
      "capabilities": [
        "mailer.updateContacts"
      ],
      "company": "OrionTest",
      "defaultAccountViewId": "100124",
      "defaultContactViewId": "100084",
      "emailAddress": "john.smith@eloqua.com",
      "loggedInAt": "1350686543",
      "loginName": "John.Smith",
      "preferences": {
        "type": "UserPreferences",
        "isMasterViewDocked": "false",
        "timezoneId": "64"
      },
      "productPermissions": [
        {
          "type": "ProductPermission",
          "productCode": "SecureHypersites"
        },
        {
          "type": "ProductPermission",
          "productCode": "EngageiPad"
        },
        {
          "type": "ProductPermission",
          "productCode": "EngageWeb"
        }
      ],
      "typePermissions": [
        {
          "type": "TypePermission",
          "objectType": "Campaign",
          "permissions": {
            "type": "TypePermissions",
            "create": "true",
            "read": "true"
          }
        },
        {
          "type": "TypePermission",
          "objectType": "Email",
          "permissions": {
            "type": "TypePermissions",
            "create": "true",
            "read": "true"
          }
     }
}
   

 

We hope that you find this helpful.

 

Thanks,

Fred

In a previous post, we demonstrated how to Search for Contacts using the Rest API. In today's post, we'll show you how to update a Contact's email address.

A complete sample project containing all of the code samples and model definitions is available here on Github.

 

The sample project on Github contains helper methods for the following operations :

  • Retrieve a single Contact
  • Search for a list of Contacts
  • Create and Update a Contact
  • Delete a Contact

 

Let's start by looking at the definition of a Contact record in the API :


public class Contact
    {
        public string accountName { get; set; }
        public string address1 { get; set; }
        public string address2 { get; set; }
        public string address3 { get; set; }
        public string businessPhone { get; set; }
        public string city { get; set; }
        public string country { get; set; }
        public string emailAddress { get; set; }
        public string firstName { get; set; }
        public int? id { get; set; }
        public string lastName { get; set; }
        public bool? isSubscribed { get; set; }
        public bool? isBounceBack { get; set; }
        public string salesPerson { get; set; }
        public string title { get; set; }
        public List<FieldValue> fieldValues { get; set; }
    }

 

Let's now look at the steps to update a Contact's email address using the API. We'll first need to identify the contact record.

There are two ways you can do this:

  1. Known Contact ID
  2. Search for the Contact

 

If you already know the ID of the contact you're working with, you can use the following method to retrieve the contact :

public Contact GetContact(int id)
        {
            var request = new RestRequest(Method.GET)
                              {
                                  Resource = "/data/contact/" + id
                              };

            var response = _client.Execute<Contact>(request);
            return response.Data;
        }


If you need to discover or search for your contact record, you can use the following method :

public RequestObjectList<Contact>SearchContacts(string searchTerm,int page,int pageSize)
        {
            var request = new RestRequest(Method.GET)
                              {
                                  Resource =
                                      string.Format("/data/contacts?depth=complete&search={0}&page={1}&count={2}",
                                                    searchTerm, page, pageSize)
                              };

            var response = _client.Execute<RequestObjectList<Contact>>(request);
            return response.Data;
        }


Finally, the project contains a method to update your contact record :

 

public Contact UpdateContact(Contact contact)
        {
            var request = new RestRequest(Method.PUT)
                              {
                                  Resource = "/data/contact/" + contact.id,
                                  RequestFormat = DataFormat.Json
                              };
            request.AddBody(contact);

            var response = _client.Execute<Contact>(request);
            return response.Data;
}


We hope that you find this helpful.


Thanks,

Fred


In a previous post, we discussed how to Send Email using the Rest API. In today's post, we'll discuss how to retrieve the statistics for your email deployment.

For a reference as well as a complete sample project on working with and sending Emails using the Rest API, please see the following Github repository.

 

Sending an Email using the API can be done by submitting a POST request to the following endpoint :

The response from the Post request will contain the unique ID for this deployment.

 

Once the email has been delivered, we can query the same endpoint (GET https://secure.eloqua.com/API/REST/1.0/assets/email/deployment/{id}) to retrieve a some statistics regarding the email delivery.

The EmailDeployment object contains a property that defines these statistics : EmailDeploymentStatistics

 

public class EmailInlineDeployment : EmailDeployment
    {
        public int? clickthroughCount { get; set; }
        public List<Contact> contacts { get; set; }
        public int? openCount { get; set; }
        public int? sendFromUserId { get; set; }
        public List<EmailDeploymentStatistics> statistics { get; set; } 
    }

 

Let's look at the EmailDeploymentStatistics object in detail.

 

public class EmailDeploymentStatistics
    {
        public string bouncebackType { get; set; }
        public int? clickThroughCount { get; set; }
        public string emailAddress { get; set; }
        public long? lastClickThrough { get; set; }
        public long? lastOpen { get; set; }
        public int? openCount { get; set; }
        public long? sentAt { get; set; }
    }

 

We hope that you find this helpful. Please note that the REST API is not yet public and the code samples referenced here are my own work. I'll be glad to support it, but please understand that Eloqua will not be able to support this code.

 

Thanks,

Fred

In previous posts, we introduced the REST API with samples in DotNet, Ruby, and PHP. In today's post, we'll introduce a request library written in Java that we're opening up to the community. The code is publicly available on Githib at : https://github.com/fredsakr/java-rest-client

 

The library supports the following operations :

  • GET
  • POST
  • PUT
  • DELETE

 

Usage

import com.rest.api.*;
Client client = new Client(site + "\\" + user, password, baseUrl);






GET

Retrieve a single entity :

Response response = client.get("/data/contact/"+String.valueOf(id));




 

Retrieve (search) for a list of entities

Response response = client.get("/data/contacts?search="+search+"&page="+page+"&count="+count);





POST

Response response = client.post("/data/contact", body);




 

PUT

int contactId = 1;
Response response = client.put("/data/contact/" + String.valueOf(contactId), body);




 

DELETE

int contactId = 1;
client.delete("/data/contact/" + String.valueOf(contactId));




 

 

Please note that 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

In this post, we'll demonstrate how to send your own custom content to a list of Contacts. In this scenario your can avoid having to create a new Email in your install for each deployment. A sample project containing all of the sources is available here on Github.

 

Let's start by defining the Email Deployment model :

 

public class EmailDeployment
    {
        public Email email { get; set; }
        public DateTime endAt { get; set; }
        public int? failedSendCount { get; set; }
        public int? id { get; set; }
        public string name { get; set; }
        public string sentSubject { get; set; }
        public string successfulSendCount { get; set; }
        public string type { get; set; }
}
    

 

The URL for Deployments :

 

Search and Retrieve Email Deployments

The details of a deployment, including number of successful sends, can be obtained post delivery.

You can search for and retrieve a list of Deployments using the following method.

 

public List <EmailDeployment> GetDeployments(string searchTerm,intpage,intpageSize)
        {
            var request = new RestRequest(Method.GET)
                              {
                                  Resource =
                                      string.Format("/assets/email/deployments?search={0}&page={1}&count={2}",
                                                    searchTerm, page, pageSize)
                              };
            var response = _client.Execute<RequestObjectList<EmailDeployment>>(request);
            return response.Data.elements;
        }
    

 

Sending an Email to a List of Contacts

When sending custom content to a list of Contacts, we'll use the following record.

 

public class EmailInlineDeployment:EmailDeployment
    {
        public int? clickthroughCount { get; set; }
        public List<Contact> contacts { get; set; }
        public int? openCount { get; set; }
        public int? sendFromUserId { get; set; }
    }
    

 

Note that the endpoint used when working with Deployments does not change :

 

Let's define the Contacts that will receive the Email.

 

var contact = new Contact()
                              {
                                  id = 152365,
                                  emailAddress = "fred.sakr@eloqua.com"
                              };
    

 

var contact2 = new Contact()
                              {
                                  id = 152366,
                                  emailAddress = "tj.fields@eloqua.com"
                              };
    

 

Let's add them to the list that will be used

 

var contacts = new List<Contact>(); 
   contacts.Add(contact);
contacts.Add(contact2);
    

 

Next, let's define the Email. Note that this object will not be created, but the Email send activity will be tracked in your install.

 

var email = new Email()
                            {
                                name = "sample email",
                                htmlContent = new RawHtmlContent()
                                                  {
                                                      html = "<html><head></head><body>test</body></html>",
                                                      type = "RawHtmlContent"
                                                  }
                            };
    

 

Finally, let's define a method that takes the list of Contacts and Email as arguments, and invokes an HTTP POST request to deliver the Email.

 

public EmailDeploymentSendCustomEmailToAddress(List<Contact>contacts,Email email)
        {
            EmailInlineDeployment deployment = new EmailInlineDeployment()
            {
                contacts = contacts,
                email = email,
                name = "sample deployment",
                type = "EmailInlineDeployment"
            };

            RestRequest request = new RestRequest(Method.POST)
            {
                Resource = "/assets/email/deployment",
                RequestFormat = DataFormat.Json
            };
            request.AddBody(deployment);

            IRestResponse<EmailDeployment> response = _client.Execute<EmailDeployment>(request);

            return response.Data;
        }
    

 

 

 

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

 

Thanks,

Fred

We previously introduced the REST API with a post on Getting Started with PHP and we recently added a PHP REST Client available here on Github.

In today's post, we'll demonstrate how to create and manage emails using the PHP REST Client.

 

Let's start by including the client.

Please note that the request library is available here on Github.

 

<?php
    // include the Eloqua REST client
    include_once('lib/eloquaRequest.php');




 

Next, let's define the models for the Email object.

 

    class Email
    {
        public $emailFooterId;
        public $emailGroupId;
        public $emailHeaderId;
        public $encodingId;
        public $htmlContent;
        public $id;
        public $name;
        public $plainText;
        public $replyToName;
        public $replyToEmail;
        public $senderEmail;
        public $senderName;
        public $sendPlainTextOnly;
        public $subject;
    }




 

The htmlContent property is a complex type :

 

class RawHtmlContent
    {
        public $type;
        public $html;
    }




 

Before making our first request, we'll need to initialize the client.

 

// initialize the client
    $client = new EloquaRequest('site', 'user', 'passowrd', 'https://secure.eloqua.com/API/REST/1.0/');




 

Retrieve a list of Emails

The following code invokes an HTTP GET request to search for and retrieve a list of Emails.

The search criteria matches the wildcard : *

 

// list emails
    $list = $client->get('assets/emails?search=*&count=50&page=1&depth=complete');




 

Create a new Email

 

$email = new Email();
    $email->name = 'sample email';
    $email->subject = 'sample subject';
    $email->emailFooterId = 1;
    $email->emailHeaderId = 1;
    $email->emailGroupId = 6;




 

Let's define the HTML content for the Email

 

    $htmlContent = new RawHtmlContent();
    $htmlContent->html = '<html><head></head><body>sample content</body></html>';




 

Finally, define the content and invoke a request to create the new Email :

 

$email->htmlContent = $htmlContent;
$response = $client->post('assets/email', $email);




 

Updating the Email

 

    $updatedEmail = new Email();
    $updatedEmail->id = $response->id;
    $updatedEmail->name = 'updated sample name';
    $updatedEmail->subject = $response->subject;
    $updatedEmail->emailFooterId = $response->emailFooterId;
    $updatedEmail->emailHeaderId = $response->emailHeaderId;
    $updatedEmail->emailGroupId = $response->emailGroupId;




 

Invoke an HTTP PUT request to update the Email :

 

$updatedEmail = $client->put('/assets/email/' . $updatedEmail->id, $updatedEmail);




 

Deleting an Email

Finally, let's clean things up. To delete an Email, invoke an HTTP DELETE request.

 

$client->delete('/assets/email/' . $updatedEmail->id);




 

 

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 support and fix issues in the code, but please understand that Eloqua will not be able to support this.

 

Thanks,

Fred

fsakr

Eloqua REST API - Sending Email

Posted by fsakr Oct 12, 2012

Eloqua will soon be exposing our web services in the form of REST Resources. The new API will give users access to create and send emails. It also provides access to manage your emails, edit content and configure details such as the sender, subject and much more. In a previous post, we demonstrated how to Create and Manage Emails using the API. In this post, we’ll describe the various types of email operations

 

There are two ways to send Email using the API :

  1. Sending an existing Email to a known Contact (EmailTestDeployment)
  2. Sending your own content (Email) to a list if known Contacts (EmailInlineDeployment)

(note that you can also send Emails to a group or segment of contacts, but this involves Campaign Canvas workflow. Please see the following post for details).

 

Both types are derived from the same base : EmailDeployment

 

public abstract class EmailDeployment
    {
        public Email email { get; set; }
        public DateTime endAt { get; set; }
        public int? failedSendCount { get; set; }
        public int? id { get; set; }
        public string name { get; set; }
        public string sentSubject { get; set; }
        public string successfulSendCount { get; set; }
        public string type { get; set; }
    } 

 

Note that this is an abstract class and when working with the API, you will need to use either of the following derived types :

  1. EmailTestDeployment
  2. EmailInlineDeployment

 

Let’s look at both types of EmailDeployment in details, starting with EmailInlineDeployments

 

EmailInlineDeployment

In this scenario, you will send your own custom content to one or many known Contacts. You can avoid having to create and retrieve emails for each operation.

Please note that these endpoints use the same functionality provided by the Engage product, as such you'll need to enable Eloqua Engage access in order to use these endpoints.

The properties on this object are :

 

public class EmailInlineDeployment : EmailDeployment
    {
        public int? clickthroughCount { get; set; }
        public List<Contact> contacts { get; set; }
        public int? openCount { get; set; }
        public int? sendFromUserId { get; set; }
    } 

 

Let’s look at a sample json request (POST) to create the Deployment.

 

{
  "clickthroughCount": null,
  "contacts": [
    {
      "emailAddress": "fred.sakr@live.com",
      "id": 152365
    }
  ],
  "openCount": null,
  "sendFromUserId": null,
  "email": {
    "htmlContent": {
      "type": "RawHtmlContent",
      "html": "<html><head></head><body>sample</body></html>"
    },
    "id": null,
    "isPlainTextEditable": false,
    "name": "sample email",
    "plainText": null,
    "sendPlainTextOnly": false,
    "subject": "sample"
  },
  "endAt": "0001-01-01T05:00:00Z",
  "failedSendCount": null,
  "name": "sample deployment",
  "sentSubject": null,
  "successfulSendCount": null,
  "type": "EmailInlineDeployment"
}

 

EmailTestDeployment

In this scenario, you will send an existing Email (already created in Eloqua) to a known Contact. The properties on this object are :

 

public class EmailTestDeployment : EmailDeployment
    {
        public int? contactId { get; set; }
        public int? sendFromUserId { get; set; }
    } 

 

Let’s look at a sample json request (POST) to create the Deployment.

 

{
  "contactId": 152365,
  "sendFromUserId": null,
  "email": {
    "bouncebackEmail": null,
    "emailFooterId": 1,
    "emailGroupId": 1,
    "emailHeaderId": 1,
    "encodingId": 1,
    "htmlContent": {
      "type": "RawHtmlContent",
      "html": "<html><head></head><body>test</body></html>"
    },
    "id": 75,
    "isPlainTextEditable": false,
    "name": "sample email",
    "plainText": "test",
    "replyToName": "PM -Test",
    "replyToEmail": "test@test.com",
    "senderEmail": "test@test.com",
    "senderName": "PM - Test",
    "sendPlainTextOnly": false,
    "subject": "sample"
  },
  "endAt": "0001-01-01T05:00:00Z",
  "failedSendCount": null,
  "name": "sample deployment",
  "sentSubject": null,
  "successfulSendCount": null,
  "type": "EmailTestDeployment"
}

 

As such, the EmailTestDeployment shares all of the properties from the EmailDeployment record, and exposes a ContactId.

The following post includes a complete project and sample code describing how to use the EmailTestDeployments.

 

Retrieve Deployment Details

You can invoke a GET request to the following endpoint to retrieve details of the deployment :

Where you append the ID of your deployment.

The response will contain details about your deployment, including number of successful sends. See the following json sample for details :

 

{
  "type": "EmailTestDeployment",
  "currentStatus": "normal",
  "id": "23",
  "depth": "complete",
  "name": "sample deployment",
  "permissions": "fullControl",
  "email": {....}
  "endAt": "1350053861",
  "failedSendCount": "0",
  "successfulSendCount": "1",
  "contactId": "152365"
}

 

We hope that you find this helpful.

 

Please note that the code 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 the code, but please understand that this code is not supported by Eloqua.

 

Thanks,

Fred

In a previous post, we discussed Authentication and Http Verb usage in the REST API. In today's post, we'll discuss request patterns.

 

We'll look at patterns and examples for the following requests :

  • Retrieve a single item
  • Retrieve a list of items
  • Create an item
  • Update an item
  • Delete an item

 

Retrieving a single item

To retrieve a single entity, a client would perform a GET request for that entity's URI, optionally specifying the format to return the entity in.

 

Request:


    GET https://.../data/contact/123
    Accept: application/json






 

Response:

    Content-Type: application/json

    {
          "type": "Contact",
          "id": "123",
          "firstName": "Joe",
          "lastName": "Smith",
    ...
    }





 

Retrieve a list of items

To retrieve a list of entities, a client would perform a GET request for that entity type's URI, specifying the query parameters to use to filter the list, and optionally specifying the format to return the entities in.

 

Request:

GET https://.../data/contacts?search=a*&count=5
    Accept: application/json





 

Response:

Content-Type: application/json

    {
        "elements": [
            {
                "type": "Contact",
                "id": "515",
                "createdAt": "1239744629",
                "depth": "minimal",
                ...
            },
            {
                "type": "Contact",
                "id": "516",
                "createdAt": "1239806222",
                "depth": "minimal",
                ...
            },
            ...
        ],
        "page": 1,
        "pageSize": 5,
        "total": 2566
    }





 

Note that the URI is the plural form of the URI of a single entity of that type. The pageSize indicates the number requested on this page, and the total indicates the total number of matches in the system.

 

Create an item

To create an entity, a client would perform a POST request to that entity's URI, specifying the format the entity is being supplied in, and optionally specifying the format to return the newly-persisted entity in.

 

Request:

    POST https://.../data/contact/
    Content-Type: application/json
    Accept: application/json

    {
          "type": "Contact",
          "firstName": "Joe",
          "lastName": "Smith",
    ...
    }




 

Response:

    Content-Type: application/json

    {
          "type": "Contact",
          "id": "123",
          "firstName": "Joe",
          "lastName": "Smith",
    ...
    }




 

Update an item

To update an entity, a client would perform a PUT request to that entity's URI, specifying the format the entity is being supplied in, and optionally specifying the format to return the newly-updated entity in.

 

Request:

    PUT https://.../data/contact/123
    Content-Type: application/json
    Accept: application/json

    {
          "type": "Contact",
          "id": "123",
          "firstName": "Joe",
          "lastName": "Smith",
    ...
    }




 

Response:

    Content-Type: application/json

    {
          "type": "Contact",
          "id": "123",
          "firstName": "Joe",
          "lastName": "Smith",
    ...
    }




 

Delete an item

To delete an entity, a client would perform a DELETE request to that entity's URI.

 

Request:

    DELETE https://.../data/contact/123




 

 

 

We hope that you find this helpful.

 

Thanks,

Fred

In a previous post, we introduced the REST API with a post on Getting Started with PHP. We recently added a PHP REST Client available here on Github.

In today's post, we'll demonstrate how to create and manage contacts using the PHP REST Client.

 

Let's start by including the client.

Please note that the client library is available here : fredsakr/eloqua-php-request · GitHub

 

<?php
// include the Eloqua REST client
include_once('lib/eloquaRequest.php');
       

 

Next, we'll define a class to represent the Contact record :

 

// define the Contact class
class Contact
{
        public $accountName;
        public $address1;
        public $address2;
        public $address3;
        public $businessPhone;
        public $city;
        public $country;
        public $emailAddress;
        public $firstName;
        public $id;
        public $lastName;
        public $isSubscribed;
        public $isBounceback;
        public $salesPerson;
        public $title;
}
       

 

We're almost ready to make our first request. First construct a new instance of the client, providing your Eloqua credentials :

 

$client = new EloquaRequest('site', 'user', 'password', 'https://secure.eloqua.com/API/REST/1.0');

 

Search Contacts

We'll invoke our first API request, to search for and retrieve a list of contacts :

 

// search for and retrieve a list contacts
$list = $client->get('/data/contacts?search=*@test.com&count=1&page=1&depth=complete');

     

 

Create Contact

The following sample creates a new contact record with Email Address : sample@test.com

 

// instantiate a new instance of the Contact class
$contact = new Contact();
$contact->firstName = 'Sample';
$contact->lastName = 'Last';
$contact->emailAddress = 'sample@test.com';
     

 

// invoke a POST request to create the contact

$response = $client->post('/data/contact', $contact);
     

 

// retrieve the ID of the new contact

$contactId = $response->id;
     

 

Update Contact

The following sample updates the contact's first name to : updated

 

// change the contact's first name
$contact->id = $contactId; 
$contact->firstName = 'updated';
    

 

// invoke a PUT request to update the contact       

$response = $client->put('/data/contact/' . $contactId, $contact);
    

 

Delete Contact

Finally, let's cleanup the record that we've created.

 

$client->delete('/data/contact/' . $contactId);
    

 

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

fsakr

Eloqua REST API - GET in Depth

Posted by fsakr Oct 6, 2012

In a previous post, we discussed the URL parameters supported by the API. In today's post, we'll focus on the Depth parameter.

The REST API can retrieve entities at three different levels of depth :

  1. minimal
  2. partial
  3. complete

 

In general, requests at minimal depth will perform best, as they scan the least amount of data. The descriptions below should help you choose the right level of depth for your request.

 

Minimal

Only a small number of the entity's properties are returned.

These are properties common to all records :

  • the entity name, type and id
  • the dates the entity was created, last updated and last accessed

Minimal depth typically results in the best performance, as the time needed to retrieve the information in minimized.

 

The following example shows a contact retrieved at minimal depth :

 

GET https://.../data/contacts?search=col&depth=minimal&count=5

 

{
    "elements": [
        {
            "type": "Contact",
            "id": "515",
            "createdAt": "1239744629",
            "depth": "minimal",
            ...
        },
        {
            "type": "Contact",
            "id": "516",
            "createdAt": "1239806222",
            "depth": "minimal",
            ...
        },
        ...
    ],
    "page": 1,
    "pageSize": 5,
    "total": 2566
}



 

Partial

All of the entity's properties are returned and if the entity is related to other objects, those entities are returned at minimal depth.

 

The following example shows a landing page retrieved at partial depth :

 

GET https://.../assets/landingPage/123?depth=partial

 

{
      "type": "LandingPage",
      "id": "123",
      "depth": "partial",
      "folderId": "456",
      "currentStatus": "Active",
      "accessedAt": "1262127601",
      "createdAt": "1250826031",
      "createdBy": "789",
      "updatedAt": "1260548979",
      "updatedBy": "123",
      "name": "My Landing Page",
      "docType": "...",
      "header": "...",
      "body": "...",
      "footer": "...",
      "layout": "...",
      ...
}



 

Complete

All of the entity's properties are returned and all related entities are returned at complete depth.

 

The following example shows a form retrieved at complete depth :

 

GET GET https://.../assets/form/1619?depth=complete

 

{
    "type": "Form",
    "currentStatus": "Draft",
    "id": "1619",
    "createdAt": "1277226536",
    "createdBy": "23",
    "depth": "complete",
    "folderId": "18071",
    "updatedAt": "1285010566",
    "updatedBy": "34",
    "elements": [
        {
            "type": "FormField",
            "id": "4538",
            "name": "First Name",
            "instructions": "",
            "createdFromContactFieldId": "100002",
            "dataType": "text",
            "displayType": "text",
            "fieldMergeId": "143",
            "htmlName": "firstName",
            "validations": []
        },
        {
            "type": "FormField",
            "id": "4539",
            "name": "Last Name",
            "instructions": "",
            "createdFromContactFieldId": "100004",
            "dataType": "text",
            "displayType": "text",
            "fieldMergeId": "3",
            "htmlName": "lastName",
            "validations": []
        },
        ...
    ],
    ...
}


 

We hope that you find this helpful.

 

Thanks,

Fred

In most cases, Eloqua's REST API will respond to requests with the standard HTTP status code definitions.

If the API fails to validate a request, it will respond with a validation message (JSON or XML) describing the issue.

The following HTTP status code definitions should be helpful in trouble-shooting your issues.

 

Common HTTP Status Codes

 

CodeText
200OK
304Not Modified
400Bad Request
401Unauthorized
403Forbidden
429Too Many Requests
500Internal Server Error
502Bad Gateway
503Service Unavailable

 

 

400 Validation Errors

These failures are the most common and will respond with some details, including a list of validation messages.

See the examples below :

 

    [
      {
      "type":"EndpointValidationError",
      "parameter":"syncActionType",
      "value":"thisIsNotValid",
      "requirement":{
      "type":"EnumRequirement",
      "values":["add","remove",...]
    }
    }
  ]

Or

    [
      {
      "type":"ObjectValidationError",
        "property":"emailFieldId",
        "value":"0",
        "requirement":{
        "type":"IdRequirement"
        },
    "container": {
    "type": "ObjectKey",
    "objectType":"Email",
    "objectId":"1"
    "container": {
    "type": "ObjectKey",
    ...
    }
    },
    }
]
















 

Error Types

  • EndpointParameterError : caused by incorrect input parameters
  • BooleanRequirement : the value must be either "true" or "false"
  • ContentRequirement : the content supplied is blacklisted
  • DateRequirement : the value must be a proper date
  • IdRequirement : the value must be an integer greater than 0
  • ImmutabilityRequirement : the value cannot be changed once it has been set
  • IntegerRequirement : the value should be an integer
  • NoDuplicatesRequirement : there is a duplicate value supplied in the request
  • NotNullRequirement : the value cannot be null or missing
  • ObjectValidationError : a problem with one of the properties on the object
  • RelationshipRequirement : a relationship between two objects or related properties has not been met
  • SyntaxRequirement : the HTML is not valid or could not be parsed
  • UniquenessRequirement : the supplied name is not unique
  • UrlRequirement : the supplied value should be a valid url

 

We hope that you find this helpful.

 

Thanks,

Fred

In a previous post, we discussed how to Create and Manage Emails using the REST API. In today's post, we'll discuss Custom Objects.

We'll cover the following operations :

  • Retrive a Custom Object by ID
  • Search for Custom Objects
  • Create and Update Custom Objects
  • Delete Custom Objects

 

The sample code is available on Github : eloqua-samples/customObject-helper at master · fredsakr/eloqua-samples · GitHub

 

Searching for Custom Objects

The search operation has 3 arguments :

  • searchTerm : specifies the search criteria to use to filter the Custom Objects
  • page : the page of entities to return
  • pageSize : the number of entities to return

 

The following request will search for and retrieve a list of Custom Objects

 

public SearchResponse<CustomObject> SearchCustomObjects(string searchTerm, int page, int pageSize)
        {
            var request = new RestRequest(Method.GET)
                              {
                                  RequestFormat = DataFormat.Json,
                                  Resource =
                                      string.Format(
                                          "/assets/customObjects?depth=complete&search={0}&page={1}&count={2}",
                                          searchTerm, page, pageSize)
                              };

            var response = _client.Execute<SearchResponse<CustomObject>>(request);

            return response.Data;
}
        

 

Creating Custom Objects

The following properties are available on the Custom Object model :

  • displayNameFIeldId : the id of the field containing the display name
  • fields : List<CustomObjectField> // see sample code for model definition
  • id : <int>
  • name : <string>
  • uniqueCodeFieldId : the id of the unique code field

 

Let's start by defining a new object :

 

var customObject = new CustomObject
                                   {
                                       id = -10001,
                                       name = "sample",
                                       fields = new List<CustomObjectField>
                                                    {
                                                        new CustomObjectField
                                                            {
                                                                name = "sample text field",
                                                                dataType = Enum.GetName(typeof(DataType), DataType.text),
                                                                type = "CustomObjectField"
                                                            },
                                                        new CustomObjectField
                                                            {
                                                                name = "sample numeric field",
                                                                dataType = Enum.GetName(typeof(DataType), DataType.numeric),
                                                                type = "CustomObjectField"
                                                            },
                                                        new CustomObjectField
                                                            {
                                                                name = "sample date field",
                                                                dataType = Enum.GetName(typeof(DataType), DataType.date),
                                                                type = "CustomObjectField"
                                                            }
                                                    }
                                   };
        

 

The following method invokes an HTTP Post request to create the record :

 

public CustomObject CreateCustomObject(CustomObjectcustomObject)
        {
            var request = new RestRequest(Method.POST)
                              {
                                  RequestFormat = DataFormat.Json,
                                  Resource = "/assets/customObject"
                              };
            request.AddBody(customObject);

            var response = _client.Execute<CustomObject>(request);

            return response.Data;
        }
        

 

 

Samples for the update and delete API operations are available in the project on Github.

 

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

 

 

Cloud Connectors

 

Cloud Connectors allow you to extend the functionality of Program Builder or the the Campaign Canvas.  Build an application that you host outside of Eloqua, and use the ExternalActionService (or Cloud Connector) API to poll a step in a campaign, retrieve its members, and perform an action on them.  Examples of these actions could be to pull in data to append to a contact record from external systems, or trigger a registration for an event by passing the contacts information to an event provider.

 

For more information, see the Cloud Connectors section in the resource guide HERE.

 

Cloud Components (Deprecated)

 

     We are no longer accepting submissions for Cloud Components.  Until further notice, existing components will continue to work as usual, but no changes can be made to the provider definition.

 

     A new framework is now available, that contains the next version of Cloud Components, called AppCloud Content.


     The documentation for this framework can be found here:

 

http://docs.oracle.com/cloud/latest/marketingcs_gs/OMCBA/index.html

 

 

Feeders

 

A Feeder is an application that "feeds" data into an Eloqua instance, usually creating new contacts as leads, or appending data to an existing contact.  These applications are configured by the user outside of Eloqua, and generally run on a scheduled basis.  Common settings required by a feeder include credentials, field mappings, and contact lists for results.  The Eloqua APIs are used to create or modify contacts, companies, and custom data objects.

 

For more information on Feeders, see Building Cloud Connectors: What is a Feeder?