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!