Determining base URLs

Eloqua supports multiple data centers, and the endpoint allows you to interface with Eloqua regardless of where the Eloqua install is located.

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. There are many cases where the base URL used for API access would change.

Previously, almost all customers resided in the same production environment, and the API was accessed using the base URL was Now the 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 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):
     Authorization: Basic XXXXX... 

    For more details, see basic authentication.

  2. If you receive a success response, the response body will look like:
     HTTP/1.1 200 OK
    Content-Type: application/json; charset=utf-8
    Content-Length: 824

    "site": {
    "id": 42,
    "name": "MyTestInstall"
    "user": {
    "id": 314,
    "username": "jane.smith",
    "displayName": "Jane Smith",
    "firstName": "Jane",
    "lastName": "Smith",
    "emailAddress": ""
    "urls": {
    "base": "",
    "apis": {
    "soap": {
    "standard": "{version}/Service.svc",
    "email": "{version}/EmailService.svc",
    "externalAction": "{version}/ExternalActionService.svc"
    "rest": {
    "standard": "{version}/",
    "bulk": "{version}/"

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

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

    "Not authenticated."
  3. Now that you have the base URL, you can use it in your code. In the above example, you would use 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.

    Warning: 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.

    Note: 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 flowchart showing the fallback process:

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