Eloqua supports multiple data centers, each with a unique domain name. Eloqua refers to these as "pods", there are currently seven in total - p01, p02, p03, p04, p06, p07, and p08. The https://login.eloqua.com/id endpoint allows you to programmatically discover a given Eloqua instance's pod, associated domain name, and base URL, which is required for making API calls to the instance.

Validate your base URL before making any API calls. If you do not 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. For any application that will be built and used by many customers, base URL discovery should be built into the your app. While not common, there are cases where an instance's base URL will change (moving an instance between pods).

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://secure.p03.eloqua.com",
       "apis": {
         "soap": {
           "standard": "https://secure.p03.eloqua.com/API/{version}/Service.svc",
           "dataTransfer": "https://secure.p03.eloqua.com/API/{version}/DataTransferService.svc",
           "email": "https://secure.p03.com/API/{version}/EmailService.svc",
           "externalAction": "https://secure.p03.eloqua.com/API/{version}/ExternalActionService.svc"
         },
         "rest": {
           "standard": "https://secure.p03.eloqua.com/API/REST/{version}/",
           "bulk": "https://secure.p03.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://secure.p03.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.