Eloqua Developer Resources and Frequently Asked Questions

Getting started video

• cURL request formatting

• Sending API requests using cURL

• Developer Help Center: Getting started topics, tutorials, Changelog, and all developer framework documentation

• Developer Tools: Developer Community to ask questions, see best practices, and learn of product notices

• Endpoint Documentation: Swagger-driven endpoint documentation for all supported API endpoints

The endpoint is not officially supported or maintained, and usage of this endpoint is at your own risk, which includes they may change breaking a built integration, usage is not documented or supported, and there could be performance issues.

Please submit a Feature Request with a detailed use case, so it could be considered to be supported in the future.

When it comes to the Application API endpoints, when an endpoint is unsupported, typically it falls into two categories of why:

1. Unintentionally not supported (e.g. there is no specific reason the endpoint is not supported, but proper investigation on impact is required to consider supporting)

2. Intentionally not supported (e.g. there are performance issues with supporting this endpoint)

Please submit a Feature Request with a detailed use case, so it could be considered to be supported in the future.

Summary of key features helps determine what will be needed for an integration.

• Moving large volumes of data? You’ll be using the Bulk API. (Build for high volumes of data with asynchronous pattern)

• Interacting with Eloqua assets? You’ll be using the Application API. (The only option to interact with assets)

• Need to build an extension right in Eloqua? You’ll be using the Developer Framework.

It’s common for integrations to include 2 out of 3, if not all of the APIs and Developer Framework.

See Selecting an API for more information.

It's a bug if the capability worked previously and no longer works.

When it comes to the Application API endpoints and the URL parameters, when something doesn't work it typically falls into two categories of why:

1. Unintentionally not included (e.g. Eloqua itself, for which these endpoints were designed for, did not need this capability)

2. Intentionally not included (e.g. there are performance issues with providing this capability)

Please submit a Feature Request with a detailed use case, so it could be considered to be supported in the future.

If the property is not returned at complete depth it is not used by the endpoint. In the future we are looking at improving our Swagger docs to not show properties that are not used by the endpoint.

The are two primary reasons they don't match:

1. Any data pulled from APIs does not include activity from deleted Contacts. Insight includes activity from deleted Contacts.

2. Label-based Access Control (LBAC), if it's being used. The APIs respect LBAC, so sometimes the user placing the API request doesn't have access to view Contacts, or the User doesn't have access to view Contacts in Insight. Additionally, non contact related reports in Insight are not limited to the contacts that a user can access. For example, a campaign report will show data related to all campaign members.

Exporting All Eloqua Activities Using the Bulk API: Flowchart, Best Practices, and Resources

Asynchronous Flow

Importing Data

Exporting Data

Given the Application API is synchronous, if there are timeouts, the number of assets returned in a request should be reduced, if retrieving data, and, the amount of data in a single request should be reduced if uploading data. Whether retrieving or posting data, this may also indicate that you need to place more time between requests or make less simultaneous requests.

Retrieving all assets using the Application API Example

When retrieving data, the number of assets returned per request can be reduced using the count parameter, and the number of fields can be controlled with the depth parameter. Here is an example scenario of retrieving all Campaigns using the Application API and these parameters:

1. Determine the number of Campaigns that doesn’t result in a timeout, or a long response time, by setting the count URL parameter. In this example we'll be retrieving Campaigns at complete depth, so 10 would be a good number to start with, but given the complexity, and data returned at complete depth, setting the count to 5 might be a better option.

2. Once the count is decided you can loop through all the pages to retrieve all the Campaigns.

3. To determine how many pages there are just divide total by count, and round up. In example:

   • /API/REST/2.0/assets/campaigns?depth=complete&count=10

   • /API/REST/2.0/assets/campaigns?depth=complete&count=10&page=2

   • /API/REST/2.0/assets/campaigns?depth=complete&count=10&page=3

   • …

   • /API/REST/2.0/assets/campaigns?depth=complete&count=10&page=<total/count> (always rounding up)

4. You could also just keep increasing the page URL parameter by 1 until you receive an empty result for the elements property.

Continuing this example, if you only need to retrieve modified Campaigns on a daily basis after initial retrieval of all assets, the updatedAt field could be used with the search parameter. In example:

• /API/REST/2.0/assets/campaigns?depth=complete&search='updatedAt>XXXXXXXXXX' (With XXXXXXXXX being a Unix timestamp for when the initial export started)

• If the number of modified Campaigns could cause timeouts, than you could use a similar pattern as above, using the count URL parameter along with the search parameter.

Have you tried using the Bulk API?

When working with large volumes of data, it'd be recommended to look at using the Bulk API instead of the Application API.

We want to encourage app/Bulk API usage, as long as app/Bulk API usage is not generating abusive API behavior. We advise not getting too caught up with the soft limit for Bulk API syncs, unless going over significantly, and/or observing performance issues related to the Bulk API load.

If you are going over this limit for one or more sync types, the chances of performance issues will increase with volume (meaning the higher you exceed the limit, the higher probability of experiencing performance issues). It's strongly recommended to stay as close to the soft limits as possible, to reduce the chance of performance issues. The main impact you'll see as the sync volume increases - is increased sync processing time with increased probability of performance issues. Performance issues are more likely to occur when there is a large Bulk API sync volume with other Eloqua activities (such as Lead Scoring, Form Processing, Segment Execution, and so on) occurring concurrently and/or also in large volumes. The lower the Bulk API sync volume, the smaller probability of performance issues when these other activities are occurring.

All developer product notices are posted on Developer Tools. All Eloqua product notices, including the developer product notices, are included within the Product Notices section on the Release Information page.

Significant changes, specifically changes we'd anticipate updates would be required, we will have a product notice prior to the change. All other smaller changes and new features are included in the Changelog. The Changelog notes are included in the New Feature Summary and What's New pages posted on the Cloud Readiness site (links to 19A pages as an example).

The Application API for the most part respects the Action Permissions. The Bulk API only respects one Action Permission – “Manage Data Export”, which applies to exporting contacts.