About this integration
You can integrate third-party systems with Service Manager in many ways. The method you select will depend on business requirements, architectural and security constraints as well as the characteristics specific to each third-party application or service.
This document describes an integration process that has already been implemented in a customer context.
To find out more about this integration (e.g. scripts to be used), please do not hesitate to contact your EasyVista contact, or your service provider and integrator.
Integration Summary
This integration is used to retrieve all available information from your Eloqua instance using the Eloqua REST API Bulk 2.0 or the REST API 2.0 (GET method).
example Retrieve and display a list of campaigns or contacts in an Service Apps app
Integration Data Feed (direction) |
|
Authentication Type |
|
Integration Connector Options |
Service Apps


|
|
Basic Authentication
|
|
REST data source 
|
SaaS Version of Third-Party Product |
On-premise Version of Third-Party Product |

|

|
API detailed description
Item |
Comments |

Oracle Marketing Cloud (Eloqua) enables drive lead generation and customer retention through data management, change management and marketing transformation.
|
Date on which the information was retrieved from the software company's website: May 2016
Last known REST API name/version/date: Bulk 2.0 (REST API) & REST API 2.0 - The Bulk API is a RESTful API designed to support high volume data transfers. It can be used for CRM and data warehousing integrations and extending Eloqua's functionality.
- The REST API is used primarily for Eloqua asset management. Assets are the building blocks of Eloqua marketing campaigns.
Eloqua's REST API is synchronous and so is not recommended for use with high volumes of data. For that we recommend using Eloqua's Bulk API.
|
Getting started with Oracle Eloqua APIs
Determining base URLs For Bulk 2.0 API:
Bulk 2.0 API (REST API) Overview
Bulk 2.0 API About determining endpoint URLs
Bulk 2.0 API Limits
Bulk 2.0 Developer Guide (pdf) For REST API 2.0:
Oracle Eloqua REST API Overview
Eloqua Rest API 2.0 References
Oracle Eloqua REST API Developer Guide (pdf)
|
For Bulk 2.0 API:
https://{subdomain}.eloqua.com/api/bulk/2.0/assets/campaigns For REST API 2.0:
https://{subdomain}.eloqua.com/api/rest/2.0/assets/campaigns Notes:- When documenting a resource, Oracle uses curly brackets { } for identifiers.
- Replace {subdomain} in the URI with your subdomain name provided by Oracle.
|
N/A
|
|
For Bulk 2.0 API:- API calls: This API is "rate limited". Only a certain number of syncs are allowed: 2,000 syncs every 24 hours. Additionnal limits:
- Import Limits:
- Maximum of 100 fields
- Hard limit of 32 MB per request
- Staging limit: It is recommended to sync an import whenever approximately 250 MB of data has been posted to its staging area
- Export Limits:
- Maximum of 250 fields
- There is a limit of 50,000 records per request
- When exporting activities there is a limit of 5 million records per sync
- Pagination: By default, endpoints return a maximum of 1000 records per page. You can change the number of records on a per-request basis by passing a limit parameter in the request URL parameters.
example limit=500 However, you cannot exceed 1000 records per page. You can specify an offset that allows you to retrieve the next batch of records. For example, if your limit is 1000, specifying an offset of 1000 will return records 1000 through 2000. example offset=1000 For REST API 2.0:- API calls: No data avaiblable
|
For Bulk 2.0 API:
According to Oracle: - "The Bulk API is a RESTful API designed to support high volume data transfers. It can be used for CRM and data warehousing integrations and extending Eloqua's functionality."
- "Some Eloqua instances enable contact-level security, which restricts access to data based on different user roles...Because these permissions affect what data the user can access, it is important that the Eloqua user accessing the API has the appropriate permissions."
- For Sortering/Ordering: orderBy specifies the name of the property to order the results by. The format is < term > ASC | DESC.
example orderBy=name ASC - For Filtering/Searching: The Bulk API 2.0 supports complex filters that filter based on multiple criteria using the AND, OR, and NOT operators.
q: Specifies query criteria used to filter results. The format is < term >< operator >< value >.
example name='Email*' For REST API 2.0:
According to Oracle: - "Eloqua's REST API is synchronous and so is not recommended for use with high volumes of data. For that we recommend using Eloqua's Bulk API."
- "The REST API is used primarily for Eloqua asset management. Assets are the building blocks of Eloqua marketing campaigns ..."
- "Some Eloqua instances enable contact-level security, which restricts access to data based on different user roles...Because these permissions affect what data the user can access, it is important that the Eloqua user accessing the API has the appropriate permissions."
- For Sortering/Ordering:
- Sort: Specifies the name of the property used to sort the returned entities. The value depends on the type of entity being sorted, with each entity having its own list of sortable properties.
example GET .../data/contacts?sort=firstName - Dir: Specifies the direction in which to sort the returned entities. asc for ascending or desc for descending.
example GET .../data/contacts?sort=firstName&dir=asc - OrderBy: Specified the field by which list results are ordered. Any valid asset parameter field.
example ?orderBy=createdAt
- For Filtering/Searching:
- Search: Specifies the search criteria used to retrieve entities. [{term} {operator}] {value} where:
- {term} is the name of a field to filter on
- {operator} is the comparison operator
- {value} is the value to compare the field with
- If {term} and {operator} are not supplied, the name field is compared to the value using the equality operator. Searches for exact full matches, and a * symbol can be used as a wildcard for partial matches.
|
Step-by-step integration process
Oracle Eloqua can be integrated with Service Apps in 4 easy steps:
Step 1: Check the list of prerequisites
- This documentation assumes that you already have an Eloqua instance and an account on that instance.
- The Bulk API is designed to let developers start developing with minimal setup or configuration effort. Nethertheless, in order to be able to interact with your Eloqua data, your account needs adequate permissions to access contact fields, secondary assets, and so on.
- Make sure that the user account you will use belongs to the Security Group API Users.

Note: Some Eloqua instances enable contact-level security, which restricts access to data based on different user roles. Users might only have access to contacts located in their geographical region, for instance. Because these permissions affect what data the user can access, it is important that the Eloqua user accessing the API has the appropriate permissions.
Step 2: Start the process for creating the REST data source
For details about the creation, see the wiki page REST data source
- Click
in the Objects pane. - Open the Online category and select the REST data source
. - Name the data source.
example Eloqua_List of Contacts Lists
Step 3: Authenticate to Oracle Marketing Cloud/Eloqua
Authenticate to Oracle Marketing Cloud/Eloqua with Basic Access Authentication
- Select the type of authentication: Authentication Type = Basic.
- Click
next to the Basic Authentication Parameters field. - Enter the User Name using the following format: CompanyName\EloquaUserName. Enter the Password.

- The user name is composed of your Oracle Cloud Marketing/Eloqua CompanyName and account/login you want to use for this data source (separated with a \).
- The password is the password set for this account.
- Once you validate, the *** symbols will appear in the field.
Step 4: Create a query string using Oracle Marketing Cloud/Eloqua documentation
See the Oracle Marketing Cloud/Eloqua API documentation for details
See Examples of use cases
- Create a query string as a data source, i.e. a resource to access, in the URL field.
example You want to create a data source that will retrieve a list of all campaign assets ordered by ascending order and ordered by creation date with a minimum of information (parameter depth=minimal), with the REST API 2.0 ==> Enter the following text in the URL field. Note: Replace {subdomain} with the name of your Oracle Marketing Cloud/Eloqua instance.
https://{subdomain}.eloqua.com/API/REST/2.0/assets/campaigns?depth=minimal&dir=asc&orderBy=createdAt
Best Practice
See Best Practice for the REST data source
- By default, Eloqua list endpoints return a maximum of 1000 records per page. To keep the number of records as low as possible, we recommend that you define as many parameters as possible.
- For the REST API 2.0 you can also use the parameter depth with the value minimal to reduce the number of information returned and the size of Json flows.
Samples of most relevant use cases and resources
Notes:
- Replace {subdomain} in the URI with your subdomain name provided by Oracle.
Method: GET
Use Case |
Sample Endpoint |
Retrieve a list of contact segments
==> with Bulk API 2.0
|
Authentication Type: |
Basic Access Authentication |
Basic Authentication Parameters: |
User Name: {CompanyName}\{EloquaUserName} Password: {Password} |
Label: |
Retrieve a list of contact segments |
URI: |
https://{subdomain}.eloqua.com/api/bulk/2.0/contacts/segments |
Description: |
Retrieve a list of contact segments for our Instance |
Selector: |
.items |
|
Retrieve a list of account list definitions
==> with Bulk API 2.0
|
Authentication Type: |
Basic Access Authentication |
Basic Authentication Parameters: |
User Name: {CompanyName}\{EloquaUserName} Password: {Password} |
Label: |
Retrieve a list of account list definitions |
URI: |
https://{subdomain}.eloqua.com/api/bulk/2.0/accounts/lists |
Description: |
Retrieve a list of account list definitions for our Instance |
Selector: |
N/A |
|
Retrieve a list of activity import definitions
==> with Bulk API 2.0
|
Authentication Type: |
Basic Access Authentication |
Basic Authentication Parameters: |
User Name: {CompanyName}\{EloquaUserName} Password: {Password} |
Label: |
Retrieve a list of activity import definitions for our Instance
Activities are entities which track certain defined online behavior for individual contacts.
Activity elements behave differently from other Eloqua elements: each activity type has its own set of associated fields
|
URI: |
https://{subdomain}.eloqua.com/api/bulk/2.0/activities/imports |
Description: |
Retrieve a list of contact segments for our Instance |
Selector: |
N/A |
|
Retrieve a list of contact lists
==> with Bulk API 2.0
|
Authentication Type: |
Basic Access Authentication |
Basic Authentication Parameters: |
User Name: {CompanyName}\{EloquaUserName} Password: {Password} |
Label: |
Retrieve a list of contact lists |
URI: |
https://{subdomain}.eloqua.com/api/bulk/2.0/contacts/lists |
Description: |
Retrieve a list of contact lists for our Instance |
Selector: |
.items |
|
Retrieve a list of contact export definitions
==> with Bulk API 2.0
|
Authentication Type: |
Basic Access Authentication |
Basic Authentication Parameters: |
User Name: {CompanyName}\{EloquaUserName} Password: {Password} |
Label: |
Retrieve all campaign assets |
URI: |
https://{subdomain}.eloqua.com/api/bulk/2.0/contacts/exports |
Description: |
Retrieve a list of contact export definitions for our Instance |
Selector: |
N/A |
|
Retrieve all campaign assets
==> with REST API 2.0
|
Authentication Type: |
Basic Access Authentication |
Basic Authentication Parameters: |
User Name: {CompanyName}\{EloquaUserName} Password: {Password} |
Label: |
Retrieve a list of contact export definitions |
URI: |
https://{subdomain}.eloqua.com/api/rest/2.0/assets/campaigns |
Description: |
Retrieve all campaign assets for our Instance |
Selector: |
.name |
|
Retrieve all visitor data
==> with REST API 2.0
|
Authentication Type: |
Basic Access Authentication |
Basic Authentication Parameters: |
User Name: {CompanyName}\{EloquaUserName} Password: {Password} |
Label: |
Retrieve all visitor data |
URI: |
https://{subdomain}.eloqua.com/api/rest/2.0/data/visitors |
Description: |
Retrieve all visitor data for our Instance |
Selector: |
N/A |
|
Retrieve a list of all the external assets
==> with REST API 2.0
|
Authentication Type: |
Basic Access Authentication |
Basic Authentication Parameters: |
User Name: {CompanyName}\{EloquaUserName} Password: {Password} |
Label: |
Retrieve a list of all the external assets |
URI: |
https://{subdomain}.eloqua.com/api/rest/2.0/assets/externals |
Description: |
Retrieve a list of all the external assets associated for our Instance |
Selector: |
N/A |
|
Retrieve all external assets type
==> with REST API 2.0
|
Authentication Type: |
Basic Access Authentication |
Basic Authentication Parameters: |
User Name: {CompanyName}\{EloquaUserName} Password: {Password} |
Label: |
Retrieve all external assets type |
URI: |
https://{subdomain}.eloqua.com/api/rest/2.0/assets/external/types |
Description: |
Retrieve all external assets type for our Instance |
Selector: |
.name |
|
Retrieve a list of email groups
==> with REST API 2.0
|
Authentication Type: |
Basic Access Authentication |
Basic Authentication Parameters: |
User Name: {CompanyName}\{EloquaUserName} Password: {Password} |
Label: |
Retrieve a list of email groups |
URI: |
https://{subdomain}.eloqua.com/api/rest/2.0/emailGroups |
Description: |
Retrieve a list of email groups for our Instance |
Selector: |
N/A |
|
Retrieve a list of all campaign assets:- ordered by ascending order
- and ordered by creation date with a minimum of information (parameter depth=minimal)
==> with REST API 2.0
|
Authentication Type: |
Basic Access Authentication |
Basic Authentication Parameters: |
User Name: {CompanyName}\{EloquaUserName} Password: {Password} |
Label: |
Retrieve a list of all campaign assets ordered by ascending order and ordered by creation date with a minimum of information |
URI: |
https://{subdomain}.eloqua.com/api/rest/2.0/assets/campaigns?depth=minimal&dir=asc&orderBy=createdAt |
Description: |
Retrieve a list of all campaign assets ordered by ascending order and ordered by creation date with a minimum of information (parameter depth=minimal) for our Instance |
Selector: |
.name |
|
Caution : The possible cost of the use of the third-parties API REST via Service Apps is not taken care by EasyVista.
- Numerous software companies limit the access to the API REST of their software, generally by basing itself on a number of calls by hour/day/month.
- Only specific editions of their software can be eligible in the use of the API REST (with or without additional cost).
- Some software companies set up plans, e.g., Classic, Professional, Enterprise, for which the number of possible calls to the REST API or even to specific resources (i.e. endpoints) can be more or less numerous.