Determining base URLs

Eloqua supports multiple data centers, and the https://login.eloqua.com/id endpoint allows you to interface with Eloqua regardless of where the Eloqua install is located.

It's important to validate your base URL before making any API calls. If you don't validate, your API calls may not work. New Eloqua users may be added to different data centers, and some Eloqua instances may periodically move between data centers. There are many cases where the base URL used for API access would change.

The https://login.eloqua.com/id endpoint should be used to determine the base URL for your API calls. The endpoint, when called using basic authentication or OAuth, will return details about the URLs you should be using.

Note:

To call https://login.eloqua.com/id you need, at a minimum, the Advanced Users - Marketing permissions for your Eloqua instance.

To determine your base URL:

  1. Send an authenticated request (in this example we use basic authentication, but OAuth2 is generally recommended as a more secure option):

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

    See Basic Authentication for more information

  2. If you receive a success response, the response body will look like:

    
     {
      "site": {
        "id": 42,
        "name": "MyTestInstall"
      },
      "user": {
        "id": 314,
        "username": "jane.smith",
        "displayName": "Jane Smith",
        "firstName": "Jane",
        "lastName": "Smith",
        "emailAddress": "jane.smith@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}/"
          }
        }
      }
     }
    
    						

    If you receive a failure response, the response body will look like:

    
    "Not authenticated."
    						
  3. Now that you have the base URL, you can use it in your code. In the above example, you would use https://www05.secure.eloqua.com as the base URL for any API calls you make to Eloqua.

  4. Cache the data from the /id endpoint for the duration of the user's session or for a reasonable period of time.

    Note:

    Do not call the /id endpoint each time you make an API call. There will be throttling or rate-limiting imposed on the /id endpoint to prevent this behavior. Instead, call it once per session (or after a reasonable period of time) and cache the results.

    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.