Skip navigation

Important:  Documentation for this topic is available in our new Oracle Eloqua Developer Help Center.


Eloqua recently made some infrastructure changes in support of additional data centers.  To support these additional data centers, a new API endpoint was created to allow you to interface with Eloqua regardless of where the Eloqua install is located.  In this post we share details of this new endpoint.

 

Until now, almost all customers resided in the same production environment.  The API could therefore be accessed using the base URL of https://secure.eloqua.com.  In the coming months, new customers will be deployed in the new data centers, and some customers may move between data centers, and will therefore have a different URL than what you have seen in the past.

 

What does this mean to you as a developer?

 

Depending on the Eloqua customer that is trying to use your app, your API calls may no longer work!

 

Here's the good news...

 

There is now an endpoint that allows you to determine the URL for your API calls.  This endpoint is https://login.eloqua.com/id.

 

The endpoint, when called with basic authentication or OAuth authentication, will return details about the URLs for the various APIs.

 

Here's how to use it:

 

Request (basic authentication):

GET https://login.eloqua.com/id HTTP/1.1
Authorization: Basic XXXXX

 

Response (success):

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 824

 

{
    "site": {
        "id": 42,
        "name": "MyTestInstall"
    },
    "user": {
        "id": 314,
        "username": "TJ.Fields",
        "displayName": "TJ Fields",
        "firstName": "TJ",
        "lastName": "Fields",
        "emailAddress": "tj.fields@eloqua.com"
    },
    "urls": {
        "base": "https://www05.secure.eloqua.com",
        "apis": {
            "soap": {
                "standard": "https://www05.secure.eloqua.com/API/{version}/Service.svc",
                "dataTransfer": "https://www05.secure.eloqua.com/API/{version}/DataTransferService.svc",
                "email": "https://www05.secure.eloqua.com/API/{version}/EmailService.svc",
                "externalAction": "https://www05.secure.eloqua.com/API/{version}/ExternalActionService.svc"
            },
            "rest": {
                "standard": "https://www05.secure.eloqua.com/API/REST/{version}/",
                "bulk": "https://www05.secure.eloqua.com/API/Bulk/{version}/"
            }
        }
    }
}

Now that you have the URLs for the API(s), you can use them in your code.


Response (failure):

HTTP/1.1 200 OK

Content-Type: application/json; charset=utf-8

Content-Length: 20

 

"Not authenticated."


Your applications must cache the data they need from the /id endpoint for the duration of the user's session or for a reasonable period of time:

 

They must not call the /id endpoint once per API call, as there will be throttling or rate-limiting imposed on the /id endpoint to prevent this behavior:

 

Tip: When calling this endpoint from a  Cloud Connector or Cloud Component app,  if an API call fails with a 401, your application should call the /id endpoint again to determine whether the 401 was the result of the user's credentials/token being invalidated, or the result of the site being moved to a different data center.  If the /id endpoint returns a failure, your application should stop making API calls.  If the /id endpoint returns a success, your application should retry the API call at the new address in the response.

 

Here's a quick flowchart showing the fallback process:

image.png

 

 

Interactive applications can respond to 401s using this process, or by simply logging the user out.

 

Frequently Asked Questions

 

  • Q: What URL should I use?
    • A: Use login.eloqua.com/id to determine your base URL, and use the base with your existing calls.
  • Q: What permissions do I need to call login.eloqua.com/id?
    • A: The user calling login.eloqua.com/id needs, at a minimum, the API Users and Advanced Users - Marketing permissions.

 

 

If you have any questions, post a Discussion to Code It!

In previous posts about building cloud components, specifically in reference to the renderInstance endpoint, we touched on the ability to receive additional parameters from the Cloud Components framework.

 

By adding extra query string parameters to your endpoint address, an Asset ID, Contact ID, or Visitor ID can be passed by the Eloqua platform into your application.

 

As an example, let's look at the following endpoint address.

 

https://mycompany.com/ccpservice/components/render/{Id}&assetId={AssetId}&contactId={ContactId}&visitorId={VisitorId}

 

Notice that, in addition to the {Id} parameter, this service is requesting values be merged into {AssetId}, {ContactId}, and {VisitorId}.  When the Eloqua landing page is rendered, and this endpoint is called, the landing page ID (AssetId), Eloqua contact ID of the page visitor (ContactId), and Eloqua visitor ID (VisitorId) will be passed to your application.  (Note: The contact ID and visitor ID will only be populated if the page visitor is a known Eloqua contact or cookied visitor)

 

Once your application receives these values, you can use them to "personalize" your component.  For instance, using the contact ID or visitor ID and the Eloqua API, you could look-up other information on the page visitor and use that to display targeted content.  Or, if you are a video provider, you could use this information to track viewing data, and build a Feeder to pass the data back into Eloqua.

 

As you can see, there are many possibilities, and I think you'll agree that this is a pretty powerful capability.

 

Keep this in mind when you are building your component!


In case you missed the post, I thought this one was worth mentioning again.

 

There is now a great reference guide available that describes how to Import and Export data using Eloqua's Bulk API (an extremely powerful new RESTful API for performing bulk operations).

 

You can find the document here: Eloqua Bulk API 1.0: Importing and Exporting Data

 

Happy coding!!!

When it comes to building cloud connectors, one of the most frequently requested features is the ability to have Eloqua *push* notifications out to an app, instead of having to go through the process of polling for members.

 

Well, I am very happy to report that the Eloqua platform development team is currently working on a framework for doing exactly this.

 

There are still few details, and a release date is not yet available, but it should work something like this:

 

When setting up your cloud connector within Eloqua, you will have the ability to specify a "callback" URL.  When an Eloqua program runs, and a Cloud Connector step is encountered, it will call this URL and notify you that your step now has members ready for processing by your app.  You can then take this information and call into the step to retrieve the members and process them accordingly.  Instead of polling on a scheduled basis, your app can simply wait until it is called in order to act.

 

I will post further updates as I have them, but thought I'd share this bit of really good news!