Eloqua web services api 1.2 user guide v1.0.1

© 2008-2014 Oracle Corporation. All rights are reserved. Trademarks Eloqua™, Eloqua Conversion Suite™, Eloqua Lite™, Eloqua
Express™, Eloqua Team™, Eloqua Enterprise™, and Eloqua Hypersites™ are trademarks or registered trademarks of Eloqua Corporation.
All other products mentioned are trademarks or registered trademarks of their respective owners.
ELOQUA USER GUIDE
WEB SERVICES API V1.2
VERSION 1.0.1
FEBRUARY 7, 2014

866 327 8764 · www.eloqua.com © 2008-2014 Oracle Corporation
This page was intentionally left blank.

TABLE OF CONTENTS
Conventions Used in This User Guide ............................................................... 1
About Eloqua ........................................................................................................ 1
About Web Services ............................................................................................ 1
Possible Uses of the API ..................................................................................... 2
Eloqua API ............................................................................................................ 2
SUPPORTED PLATFORMS ......................................................................................................... 3
STANDARD TECHNOLOGIES ..................................................................................................... 3
ELOQUA API SUPPORT POLICY ................................................................................................ 3
RELATED RESOURCES .............................................................................................................. 3
END OF LIFE ................................................................................................................................ 4
Getting Started ..................................................................................................... 4
STEP 1: REQUEST THE WEB SERVICES API INTEGRATION ................................................... 4
STEP 2: OBTAIN COMPANY NAME, USERNAME, AND PASSWORD ....................................... 4
STEP 3: RETRIEVE WSDL ........................................................................................................... 4
STEP 4: IMPORT WSDL ............................................................................................................... 5
FOR JAVA ............................................................................................................................... 5
FOR VISUAL STUDIO ............................................................................................................. 6
STEP 5: WRITE THE CODE REQUIRED ...................................................................................... 7
Eloqua Objects Overview .................................................................................... 7
Object Model ......................................................................................................... 7
ENTITIES ...................................................................................................................................... 7
ENTITY RELATIONSHIPS ............................................................................................................ 8
ENTITY METADATA ..................................................................................................................... 9
...................................................................................................................................................... 9
ENTITY - GLOBAL TYPES ......................................................................................................... 10
BASE ENTITY TYPES ................................................................................................................ 10
ASSETS ...................................................................................................................................... 11
ASSET METADATA ................................................................................................................... 11
CRM INTEGRATION CONSIDERATIONS .................................................................................. 12
SCENARIO 1: MARKETING ACTIVITY INTEGRATION ............................................................ 13
PROCESSED ACTIVITY QUEUE ............................................................................................... 14
SCENARIO 2: SYNCHRONIZE LEAD/CONTACT DATA ........................................................... 16
CRM/ELOQUA DATA MODEL ................................................................................................... 17
FIELD TYPES ............................................................................................................................. 18
SECURITY .................................................................................................................................. 19
SYSTEM FIELDS ........................................................................................................................ 20
API Call Basics ................................................................................................... 20

API CALL CHARACTERISTICS ................................................................................................. 20
ERROR HANDLING .................................................................................................................... 20
Additional Considerations ................................................................................ 21
USAGE METERING .................................................................................................................... 21
COMPRESSION ......................................................................................................................... 22
INTERNATIONAL CHARACTERS .............................................................................................. 22
ELOQUA IDENTIFICATION CODES .......................................................................................... 22
API Reference ..................................................................................................... 22
METADATA ................................................................................................................................ 22
ENTITY METADATA ................................................................................................................... 22
ENTITY METADATA OPERATIONS .......................................................................................... 23
LISTENTITYTYPES ............................................................................................................... 23
DESCRIBEENTITYTYPE ....................................................................................................... 25
DESCRIBEENTITY ................................................................................................................ 27
ENTITY OPERATIONS ............................................................................................................... 30
CREATE ................................................................................................................................ 30
RETRIEVE ............................................................................................................................. 34
UPDATE ................................................................................................................................ 37
DELETE ................................................................................................................................. 41
QUERY .................................................................................................................................. 44
ASSET METADATA ................................................................................................................... 48
ASSET METADATA OPERATIONS ...................................................................................... 49
LISTASSETTYPES ................................................................................................................ 49
DESCRIBEASSETTYPE ........................................................................................................ 51
Data Transfer Service ........................................................................................ 53
DATA EXPORT OPERATIONS .................................................................................................. 54
INITIALIZEDATAEXPORT ..................................................................................................... 54
DATAEXPORTSTATUS......................................................................................................... 57
GETDATAEXPORTFILE ........................................................................................................ 59
DATA IMPORT OPERATIONS ................................................................................................... 63
INITIALIZEDATAIMPORT ...................................................................................................... 63
DATAIMPORTSTATUS ......................................................................................................... 66
Errors................................................................................................................... 69

1 866 327 8764 · www.eloqua.com © 2008-2014 Oracle Corporation
Conventions Used in This User Guide
The following conventions are used in the Eloqua® Web Services API Beta v1.2 User Guide.
 Bold text is used to indicate the start of procedures (in the format "To do xyz...:").
 Bold text is used to indicate elements or controls found in the User interface.
 Bold text is used to introduce each Note, Tip and Warning! If you are viewing this document in color, a Warning! also appears using a violet-colored font.
 Text describing controls is generally included in full in procedures unless it is quite lengthy, in which case only the first word or few words are indicated followed by ellipses (for example: No, send document...).
 Path names, file names, code samples, and file extensions are rendered using the Courier New font.
About Eloqua
Eloqua Conversion Suite is the industry’s leading family of demand generation applications for business-to- business (B2B) marketers who need to generate a continuous flow of qualified leads for their sales teams. Our solutions—Eloqua Lite™, Eloqua Express™, Eloqua Team™ and Eloqua Enterprise™—integrate Email, direct mail, Forms automation, website analytics and event-triggered automation with Sales Force Automation (SFA) to continuously, repeatedly, and measurably create demand for your company’s products or services. As a result, your sales team gets better quality sales leads, higher win rates and accelerated sales cycles.
Eloqua acts as a front-end marketing database that captures Form submissions from your website and can then nurture leads before passing them into your CRM system for the salespeople to see.
For more information about Eloqua you can visit our website at www.eloqua.com or use the online documentation and training portal within the Eloqua application.
About Web Services
The term “web services” describes a standardized way of integrating Web-based applications over the Web. Web services allow organizations to communicate with each other, without intimate knowledge of each other’s IT systems.
API stands for Application Programming Interface. Simply put, the API allows a software’s functionality to be extended to 'the outside world.' Programmers can write their own code that exercises the functionality that the API exposes.
Web services rely on the following core technologies:
 Extensible Markup Language (XML)—XML is a general-purpose specification for creating custom markup languages. It is classified as an extensible language because it allows its users to define their own elements. Its primary purpose is to facilitate the sharing of structured data across different information systems, particularly via the Internet, and it is used both to encode documents and to serialize data.
 Web Services Description Language (WSDL)—WSDL, pronounced 'wiz-del' or spelled out as W-S-D-L, is an XML-based language that provides a model for describing Web services. WSDL defines services as collections of network endpoints or ports. The WSDL specification provides an XML format for documents

Eloqua® Web Services API v1.2 User Guide
for this purpose. The abstract definition of ports and messages is separated from their concrete use or instance, allowing the reuse of these definitions.
 Simple Object Access Protocol (SOAP)—SOAP is a protocol for exchanging XML-based messages over computer networks, normally using HTTP/HTTPS. SOAP forms the foundation layer of the web services protocol stack by providing a basic messaging framework upon which abstract layers can be built. Web services messages are sent between the customer implementation of Web services and the SOAP handler on the Eloqua web server.
For more information on Web services technologies, see http://www.w3.org/2002/ws.
Possible Uses of the API
The Web Services API allows companies to build programs to integrate with Eloqua. Some examples of web services integrations include the following:
 Integration between Eloqua and CRM System—You can create a connector that polls Eloqua on a regular basis for new marketing activities and Contact record changes and updates your CRM system from Eloqua. For example, instead of using flat file batch transfers for integrating Eloqua with your CRM system, you can now have near real-time updates between your systems. In addition, your CRM system can call out to Eloqua and update information in your marketing database.
 Updating Data Warehouses for analytics—Using the Eloqua Data Export service, you can now export historical transactional data about website activity, Form submissions, Email activity, and other details for analysis on a regular basis.
 Connectors to External Web Services—By creating a polling connector service that Polls Eloqua for certain actions or activities, you can trigger a web services call to another service that may append data or begin a secondary process in another system using data passed over from Eloqua.
Eloqua API
The Eloqua Web Services API is intended to provide the ability for developers to easily integrate their existing systems to the Eloqua platform and leverage its rich data store to provide actionable marketing intelligence to the enterprise. To use this document and the Eloqua API, you need to have a good grasp of fundamental web programming techniques and tools. This document will serve as a guide to the Eloqua Web Services API, but does not function as an overall guide for Eloqua and its capabilities in general.
Note: Development platforms vary in their SOAP implementations. These differences may prevent access to some or all of the features in the API. We recommend that you use Visual Studio 2005 or higher if you are using Visual Studio for .NET development.
This first version of the API is focused on providing access to the primary data entities within Eloqua and allowing developers to Create, Update, Retrieve and Delete records programmatically, as well as allowing bulk export or import of large datasets. Future versions of the API will focus on performing actions and leveraging other capabilities such as management of Contact groups, Programs, and marketing activities.

SUPPORTED PLATFORMS
The Web Services API was designed using common web technologies that allow for interoperability between systems. Specifically, the API is directly supported within two primary technology stacks: .NET and Java. The API is SOAP-based and should be accessible from other platforms not listed here, but may require libraries or components to be installed that support the appropriate standards.
The API works with current SOAP development environments, including, but not limited to, Visual Studio .NET 2008, Eclipse using Apache Axis 2 + Rampart, and NetBeans 6 using the WSIT libraries. In this document, we provide examples in Java and .NET. The Java examples are created in NetBeans 6.0.1 using the WSIT 1.1 libraries (See: https://wsit.dev.Java.net/).
For more information about Apache Axis 2, go to http://ws.apache.org/axis2/.
For more information about Rampart 1.3, go to http://ws.apache.org/axis2/modules/rampart/1_3/security- module.html.
STANDARD TECHNOLOGIES
Standard web technologies that are implemented in the Eloqua web services API include the following: Simple Object Access Protocol 1.1 http://www.w3.org/TR/2000/NOTE-SOAP-20000508/ Web Service Description Language (WSDL) 1.1 http://www.w3.org/TR/2001/NOTE-wsdl-20010315/ WSS (WS-Security, OASIS) 1.0 http://www.oasis-open.org/specs/index.php#wssv1.0
ELOQUA API SUPPORT POLICY
Eloqua suggests that any applications being written using the API use the latest release version of the API. New functionality and enhanced performance will be included and supported only on new releases of the web services API. When a new version of the API is released, you will need to retrieve a new version of the WSDL to see the new functions and schemas.
Our technical support team can provide limited assistance with API development and are mainly focused on troubleshooting and resolving errors or investigating potential bugs within the API. They cannot provide any support or advice for programming logic nor assistance with creating programs that use the API.
RELATED RESOURCES
There are numerous web resources available for getting more familiar with Eloqua’s capabilities and functions. Below, we have listed some Eloqua-specific resources that are available to users of the application.
Eloqua Training Resources Once you have logged in to the application, click on the Training button in the top right-hand corner. Eloqua Online Help When you are logged in, click Help in the upper right- hand corner to open the online Help system.

Eloqua Community Forums Go to eloquacommunity.com. Log in using your Eloqua password. There is a specific forum for API support and help.
END OF LIFE
The intention is to provide a fully backwards-compatible web services layer. However, if a change is required that would cause a loss of functionality, there would be a major API version release. Eloqua does not guarantee that an application written against one API version will work with future API versions: Changes in methods and data representations are often required to further enhance the functionality we provide. However, we make significant efforts to ensure that the API is consistent from version to version.
Getting Started
The Section below is for getting a quick start with the Eloqua API and the basic steps needed to get your first Eloqua program up and running. This first demonstration program will show an example where a Form submission to a web page could be used to create a new Contact in Eloqua and return the new EntityID of the Contact.
The steps outlined in the following sections are required for this demonstration program.
STEP 1: REQUEST THE WEB SERVICES API INTEGRATION
For security reasons, the capability to use the API is not automatically enabled for all implementations of the Eloqua application. Upon request, your Customer Success Manager (CSM) will enable the Web Service Integration for your company.
STEP 2: OBTAIN COMPANY NAME, USERNAME, AND PASSWORD
In order to use the API, you need to get login information for the Eloqua system. There are three elements needed to log in to Eloqua: CompanyName, Username, and Password. Speak to the Eloqua administrator in your organization who can create a new user account. They will need to place the username that will be used for API calls into the security group called “API Users” in order for you to be able to access the system programmatically.
After receiving your new login from your administrator, you must log in to https://secure.eloqua.com in order to change the initially-assigned password. The password you specify will be used when authenticating using the API.
It is recommended that you use a distinct user for API operations when possible to avoid administrative hassles such as a user being disabled that was used for integration purposes.
STEP 3: RETRIEVE WSDL
To access the Eloqua Web service, you need a Web Service Description Language (WSDL) file. The WSDL file defines the Web service that is available to you. Your development platform uses this WSDL to generate an API to access the Eloqua Web service it defines.
Retrieve the WSDL (Web Services Description Language) from one of the following two sources:
For Low-volume queries and entity updates use this WSDL:

https://secure.eloqua.com/API/1.2/Service.svc?wsdl
To use the Eloqua Data Import or Export engine for bulk transfer of flat files through the API use this WSDL:
https://secure.eloqua.com/API/1.2/DataTransferService.svc?wsdl
For more information about WSDL, see http://www.w3.org/TR/wsdl.
STEP 4: IMPORT WSDL
Once you have the WSDL file, you need to import it into your development platform so that your development environment can generate the necessary objects for use in building client Web service applications in that environment. This section provides sample instructions for Apache Axis (Java) and Microsoft Visual Studio. For instructions about other development platforms, see your platform’s product documentation.
FOR JAVA
To use the Eloqua API in a NetBeans project, do the following:
To install NetBeans:
1. Install the latest NetBeans with Java JDK (NetBeans 6.0.1 + JDK 6 Update 6 as of this writing).
2. Once NetBeans is installed, install the following plugins using the NetBeans Plugins module (click Tools > Plugins):
a. Web Services
b. Web Applications
c. WSDL
d. JAX-RPM Web Services
3. Download WSIT 1.1 (https://wsit.dev.Java.net/) and extract to a preferred location on your hard drive.
To create a new WSIT-enabled project:
1. Create a Java Application project in NetBeans providing any name and location you wish.
2. In the Projects window, right click on the Libraries Folder and click Add JAR/Folder.
3. Navigate to the folder where you extracted WSIT and open the lib directory.
4. Highlight all the JAR files in that folder and add them.
5. You are now ready to generate your service proxy using Eloqua’s WSDL files.
To create the web service client:
1. In the projects window, right click on your project and select New > Web Service Client.
2. Select WSDL URL and put the Eloqua wsdl URL in the textbox (https://secure.eloqua.com/API/1.2/Service.svc?wsdl).
3. Type in a package name for the Eloqua service proxy.
4. Click Finish.

To set up authentication:
1. In the projects window, expand the Web Service references folder.
2. Right click on the Eloqua service and select Edit Web Service Attributes.
3. Under the Security section, select Static authentication credentials and type in your Eloqua login credentials in the format:
Username: CompanyName/UserName
Password: Password
FOR VISUAL STUDIO
Visual Studio languages access the API through objects that serve as proxies for their server-side counterparts. Before using the API, you must first generate these objects from your organization's WSDL file.
Visual Studio provides two approaches for importing your WSDL file and generating an XML Web service client: An IDE-based approach and a command-line approach.
Note: Before you begin, the first step is to create a new application or open an existing application in Visual Studio. In addition, you need to point to the WSDL files in Eloqua.
An XML Web service client is any component or application that references and uses an XML Web service. This does not necessarily need to be a client-based application. In fact, in many cases, your XML Web service clients might be other Web applications, such as Web Forms or even other XML Web services.
When accessing XML Web services in managed code, a proxy class and the .NET Framework handle all of the infrastructure coding.
To access an XML web service from managed code:
Adding a reference to a .NET project is very straightforward. Follow the steps below:
To add the Service Reference:
1. Create a new project in any .NET language you prefer.
2. In the Solution Explorer, right click on your project and select Add Service Reference.
3. Type in the URL to the Eloqua WSDL (https://secure.eloqua.com/API/1.2/Service.svc?wsdl)
4. Provide a namespace for the Service proxy and click OK.
To set up Authentication:
Once you have your proxy setup, simply set the credentials on the proxy object to setup authentication.
C# Sample:
Suppose you called the service namespace EloquaService; the code to create a new instance of the proxy and setup authentication would look like:
EloquaService.EloquaServiceClient serviceProxy = new EloquaService.EloquaServiceClient();

serviceProxy.ClientCredentials.UserName.UserName = "Companyusername"; serviceProxy.ClientCredentials.UserName.Password = "password";
STEP 5: WRITE THE CODE REQUIRED
Once you have completed the other steps, it’s time to write the code required to implement usage of the selected Eloqua web service. You can find specific code sample to help you do this in the API Reference beginning on page 22. The code samples are provided in both .NET and Java formats.
Eloqua Objects Overview
The diagram below shows the relationships between the data entities in Eloqua. See the Entities section of the Object Model below for more information.
Object Model
The Eloqua API is separated into 3 main areas:
1. Entities
2. Assets
3. Data Services (DataExport and DataImport Functionality)
ENTITIES
The Eloqua marketing database is used for a variety of purposes including storing Contact data and transactional records such as closed opportunities (ie: Data Cards) for list segmentation purposes. Some of these entities are related to one another (ie: Companies and Contacts); others are simply transactional storage silos (ie: Form Submissions). The Eloqua Entities are represented in the API and can be “described” to determine their schema such as available fields, field types and required values.

There are two entities that are slightly different—Forms and Data Card Sets—for the reason that they represent both an Entity in Eloqua and can also be described as an Asset (for example: you can pull data from “Forms” as an Entity, but you could also configure how a Form operates or its properties because it is also an Eloqua Asset).
The Eloqua API makes use of the following DynamicEntities to store the schema by which they store data and the actual data itself:
 Contacts
 Prospects
 Companies
 Data Cards,
 Form Submissions
 Visitors
 Object Relationships
ENTITY RELATIONSHIPS
The diagram below indicates the entity relationships available through the API. Note that some relationships may not currently be visible in the API (such as a Prospect-to-Visitor relationship as the lookup tables are not exposed via the API).
ContactContactIDVisitorIDC_DateCreatedC_DateModifiedC_EmailAddressContactIDExtProspectIDCompanyIDC_EmailAddressDomainC_StandardField1C_CustomField1ProfileFieldDataVisitorIDCustomerGUIDDateCreatedDateEditedV_first_nameV_last_nameV_Total_VisitsV_IPAddressLastPollV_Total_PagesVisitorEntityTypeIDEntityIDCompanyIDV_StandardField1V_CustomField1ProspectIDDataCardIDCompanyCompanyIDM_DateCreatedM_CompanyNameM_DateModifiedCompanyIDExtM_StandardField1M_CustomField1ProspectProspectIDP_DateCreatedP_EmailAddressP_FirstNameP_LastNameCompanyIDContactIDVisitorCompanyMapCompanyIDVisitorIDVisitorProspectMapProspectIDVisitorIDDataCardDataCardIDDataCardNameDataCardSetDataCardStatusUniqueCodeSalesProcessEntityTypeSalesProcessEntityDataCardIDExtDateCreatedDateModifiedDateCompletedDataImportExecutionIDVisitorIDDataCardFieldValueDataCardFieldValueIDDataCardDataCardFieldStringValueIntegerValueTextValueDataImportSourceIDDateTimeValueNumericValueForm DataFormSubmitIDDateSubmittedVisitorIDCustomField1StandardField1InternalQueueInternalQueueIDExternalIDDateEmailAddressPriorityStatusOwnerSubjectTypeEntityID

ENTITY METADATA
The web service contains operations for discovering all the entities in the system as well as the metadata information for each entity. The following operations are available:
Entity Metadata operations:
 ListEntityTypes() Retrieve all the entity types in your Eloqua database. This includes the Base type that contains the Contact and Company entities. Only types available in the instance of Eloqua which you are logged into are returned. Your application can parse the response and query for further information such as the metadata for each Entity type.
 DescribeEntityTypes() Retrieve all the entities in a given Entity Type. For example: Contacts, Companies and Prospects are entities contained in the Base Entity Type.
 DescribeEntity() Retrieve all the metadata for a specific Entity. The information returned also contains access permissions on the entity (Readable, Createable, etc…)
Entity Metadata Diagram

ENTITY - GLOBAL TYPES
Base Objects are used to store data about marketing contacts and their related entities. These primary (Base) objects include: Contacts, Prospects and Companies, Visitors and Processed Activity. Eloqua Global Types (ListEntityTypes) Base
This type includes the 3 main Eloqua entities: Contact, Company and Prospect. These entity types can be further described to identify the metadata available (such as Field Names) and actions available. DataCardSet
DataCardSets is an entity that may have its own data model customization (customized fields per set) and store many records that are related to a single Contact record. This entity type will return a list of all the Data Card sets in the current instance. Forms
Forms is a repository of all the Form submission data that is captured by the Eloqua Form Processing engine before it is recorded into a Contact record and processed. In the Eloqua interface, this data is equivalent to opening the Form’s “Form Data Submission Report.”
BASE ENTITY TYPES
With Eloqua, built around a marketing-oriented database, there are primary or “Base” Data Objects (including Contacts, Prospects, and Companies) that are used within the system to store data about marketing contacts and their related entities. Eloqua Base Entity Types (DescribeEntityTypes:Base) Contacts
Contacts are the most frequently used entity in the Eloqua system. A Contact record typically represents a person that is either a customer or prospect who has an email address. In Eloqua, the Contact table uses email as a unique identifier to prevent duplicate Contacts from having the same email address. Prospects
Prospect records are similar to Contacts, but do not have the need to have an email address. Prospect records typically contain records of Contacts or Leads who do not have an email address. They can be converted into a Contact record through Program Builder when they acquire an email address. Companies
Company records in Eloqua (sometimes referred to as Accounts in CRM systems) represent an organization and act as a parent record to Contacts and Prospects who can be linked to a Company record. A typical Company record would contain information about the Company name, annual revenue, trading symbol, etc.

Eloqua Base Entity Types (DescribeEntityTypes:Base) Visitors
Visitor records (sometimes referred to as ‘Visitor Profiles’) are the container for each recorded visitor to your tracked website pages. Each record contains information such as browser, IP address, Geo-IP information, Linked Contact fields, Lat/Long, DNS Names, aggregated statistics about the visitor such as total pages viewed, length of last visit, last search engine keyword, and many other customizable fields. Processed Activity Queue
This object represents a queuing table that can hold marketing activities that are trigged by custom events in Program Builder or via Integration Rules. Use this mechanism to write marketing activities into your CRM system. Your system will poll the marketing activities table for any new records since the last check—the values returned will include the type of activity, date/time, Related Contact/Lead ID, and a description field. Your connector program can then write these activities as tasks into your CRM system that are related to the Contact/Lead record. You need to request Processed Activity to be turned on for a particular Eloqua instance. Speak to your CSM.
ASSETS
Assets are abstract representations of structured data in Eloqua, such as an Email Brochure or Data Import settings (AutoSynch). Eventually, the API will begin to include other Assets that are currently only accessible within the UI of the Eloqua platform. Assets are the tools that are used to make your marketing application do soemthing: Send Emails, edit Email content, create Hypersites™, add to Programs, Data Import mappings, Data Export settings and many others. In this current version of the API, only DataImport and DataExport Settings are available as Assets.
ASSET METADATA
The web service contains operations for discovering all the assets in the system as well as the metadata information for each asset. The following operations are available:
Asset Metadata operations:
 ListAssetTypes() Retrieve all the Asset Types in your Eloqua database. Only Types available in the instance of Eloqua which you are logged into are returned.
 DescribeAssetType() Retrieve all the Assets in a given Asset Type.

Asset Metadata Diagram
CRM INTEGRATION CONSIDERATIONS
Eloqua has been integrated with a variety of different CRM systems with different data models and methods of storing data and related records. Our Professional services team can help with guidance or direction with integrating with your own particular data needs. Speak to your Account Manager for more details. Eloqua supports many different methods of connecting to external systems such as batch file transfers over FTP, HTTP, HTTPS using cookie or form based logins, the Eloqua DirectConnect integration engine, and our new API.
For hosted CRM systems such as Salesforce.com®, Oracle® CRM OnDemand, Microsoft ® Dynamics CRM 4.0, and NetSuite®, Eloqua’s DirectConnect has a suite of native adapters that are used for many of our integrations. Creating your own connector using the Eloqua API for these systems is generally unnecessary.
If you have a unique or non-native CRM system that you wish to connect with Eloqua, you will likely need to build a connector that acts as the bridge between your CRM system and Eloqua using the API. The Eloqua API has been designed to allow for regular polling by your CRM connector system to find newly updated records or recently executed marketing activities.
There are three main components of data that are typically synchronized or exchanged between Eloqua and a CRM or ERP program. Not all components are required as part of an integration:
1. Marketing Activity Data
Regular marketing activities such as Email Opens, click-throughs, unsubscribes, bouncebacks, website visits, and Form submissions are typically made available to the CRM system and are sent with the

related Lead/Contact record ID so that a record can be created in the CRM that records the relationship. These activities can be used for reporting (for example, to relate activities and closed opportunities).
2. New or Updated Lead/Contact Data
a. Outbound Data from Eloqua - As website visitors submit Forms, these will update/create the Contact records in Eloqua based on the email address that is supplied with the Form submission. These records should also be pushed into a “Program” within Eloqua that may score or dictate how a record is handled after submission into the system (for example, should a record be passed to CRM only after it is scored higher than 65).
b. Inbound Data to Eloqua - New Contact records created by your sales team in the CRM also should flow into Eloqua on a regular basis so that they can be included as part of formal marketing efforts. This is often achieved by either supplying Eloqua with a a CSV file, or using Eloqua web services to create a new Contact record and passing the information from the CRM system into the new record.
3. Campaign Associations
a. Based on marketing activities, marketing teams may wish to associate a Contact or Lead record in your CRM to a Campaign object within your CRM system for basic reporting purposes. This can include creating basic ROI or influenced revenue reports within your CRM system, depending on your data requirements.
b. Typically a Contact or Lead ID and a Campign Object ID from your CRM system are needed to perform an association. This is mostly dependent on your CRM’s architecture and capabilities.
When developing an integration with Eloqua, you may choose to perform operations in Batch- or Event- driven manner from your side. Eloqua does not currently support Event-driven integrations that push data directly to an endpoint on your side, so you must poll Eloqua actively to pull down Events from the queue.
It is important that the Eloqua Entity ID is stored within your CRM system as part of the Contact or Lead record as it is needed to perform API calls efficiently back to Eloqua. While Eloqua matches records in the Contact table based on email address, the API requires the Entity ID to be used in API calls such as updating a Contact record in Eloqua when a record change occurs within your CRM system.
SCENARIO 1: MARKETING ACTIVITY INTEGRATION
In a scenario where Marketing activities must be passed over to your CRM system, there is a facility called the “Processed Activity Queue” that collects recently-triggered Eloqua marketing activities (such as Email opens, website visits, form submissions,etc.) by Contacts within the Eloqua database. These activities are polled by your code on a reguar basis and created as a records related to the Contact or Lead in your CRM system or database. Your web service will need to match a record in your CRM to update using the related records. It is possible to map your system’s Foreign Contact/Lead ID to each activity that is placed in the Processed Activity Queue for easy mapping to the record in your CRM.

PROCESSED ACTIVITY QUEUE
The Processed Activity Queue is enabled by request by your Customer Success Manager for your Eloqua instance. Processed Activity is not available if you have Instead of writing them to an external CRM system as usual, you can direct these activities to be written to the Processed Activity Table (Part of the BASE entity), which is accessible via the API and will store these records for a period of two weeks.
Before using this function, you must create an External API call that is mapped to the appropriate fields in the Processed Activity Queue by creating a new External Call in the Outbound tab in the Integration area.

Note: Eloqua Internal will only be visible if it has been enabled for your instance of Eloqua and you have Customer Administrator security rights. It is not available if you already have an integration using DirectConnect to Salesforce.com®, Oracle® CRM OnDemand, Microsoft ® Dynamics CRM 4.0, and NetSuite®.
When creating an external API call that will write to the table, you must map the fields that will be stored in the queue. You can map fields by dragging fields from the right into the columns of the Processed Activity Queue on the left:
You can run a test call that will write data to the Processed Activity Queue for testing purposes. You can view the current Mapped External Calls for an Internal Event using the View Mapped External Calls option.
Once an External Call is mapped to an Internal Event, you can run the test.

For performing the test, you will be asked to choose a Contact record in Eloqua which will fire the External Call you have specified.
SCENARIO 2: SYNCHRONIZE LEAD/CONTACT DATA
In a typical marketing database scenario, Eloqua is used as a centralized place to store and match incoming requests, Form submissions, and list uploads from marketing events. This can help avoid entries in the CRM system that may be considered to be “dirty” or duplicated. In most scenarios the CRM database is seen as the “master” database with the most up to date information.
In any case, it is critical that you sit down and evaluate the needs of the sales and marketing teams regarding what information must be exchanged between the two systems. Sales teams are generally interested in receiving information about marketing activities and lead scores, while the marketing team will

generally have an interest in leveraging segmentation data contained within the CRM to create targeted marketing campaigns.
In the diagram above, note that new Form submissions create Lead records that are pushed into the CRM system. Updates and new records in the CRM system must be pushed into Eloqua to keep the databases synchronized.
CRM/ELOQUA DATA MODEL
Each of the following Entities have their own set of fields that can be customized by the Administrator.
Contacts—The primary entity within Eloqua—Contact records—are deduplicated by their email address. You cannot create multiple Contact records with the same email address. Contact records are typically used to represent Leads and Contacts from a CRM system. You should be storing the unique identifying record ID that your CRM system uses for Leads/Contacts in an Eloqua Contact field that has been created expressly for this purpose. This can be used for rmatching purposes when exporting marketing activities.
Companies—Contacts can be linked to a Company record in Eloqua, and are typically equivalent to an “account” or “company” record in a CRM system. It is recommended that you create a field to store the ID that is used within your CRM system to identify Accounts/Company records.
Prospects—Similar to Contacts, but has no unique key requirements such as an email address. Prospects are not deduplicated and generally represent Leads or Contacts with no email address associated to them. Prospects can be linked to Companies in Eloqua. Prospect records can be converted to Contact records by using a Program Builder step to map the fields between the two entities (Prospects and Contacts) and performing the conversion.
Data Card Sets—A Data Card set typically represents an Event or series of records. Each Data Card set has it’s own fields and settings. For example, Data Card Set A may have only three fields, but Data Card set B has 20 fields. A Data Card set contains many Data Cards that may be linked to a Contact record.

Data Cards—A Data Card is the record that stores a transaction such such as an Event registration by a Contact, or a purchase history record (opportunities). Each Data Card may or may not be linked to a Contact record.
DATA WAREHOUSE INTEGRATION
Eloqua’s marketing activity data may be used to build or support a data warehouse by supplying insight into prospect activities. In a data warehouse, relationships between prospect activities, purchase history and other business variables can be measured and used in company level metrics. The Eloqua API supports the model of supplying a data warehouse with information on a regular basis in bulk file downloads.
To define and configure a data export configuration that specifies what delimiters will be used in the file, which type of information from Eloqua should be exported, and other settings, go to the Reporting Area in Eloqua and create a new Data Export. This list of automated exports are visible via the API through a describe call of the DataExportAsset.
When creating a connector for a data warehouse, the service will need to accept CSV files through a binary SOAP call and be able to manipulate the file into a format that is importable to your data warehouse. The field values that are passed over are configurable from within the Eloqua UI. Certain Reports are not configurable and come with a set series of fields/columns. See the Scheduled Report Exports documentation for more information.
Eloqua can export the following items from its historical tracking database into delimited files:
 Call On Demand, Fax, Printmail, RSS, Data Card Activity
 All Email Activity
 All Form Submissions
 Full Company/Contact/Prospect list
 Marketing Campaign Activity
These exports can be done on a regular basis by the system and can be picked up remotely without using the API. Using the API to trigger Data Exports from Eloqua allows for on-demand generation of these Reports. Generally, Data Warehouses do not require up-to-the-minute updates of information. Using the Data Export to URL functionality allows for this on a once daily basis. This would not require the use of the API to get information from Eloqua. For more information, see Eloqua Scheduled Report Exports documentation.
FIELD TYPES
The Field Types in Eloqua are configurable by the Customer Administrator and have certain attributes set for each. The field types such as Picklist, Multi-select, and Text, are generally used to represent data within the Eloqua UI. However, at the data layer in the Eloqua database, only the actual value is required and stored.
Picklist fields are represented as a standard text field via the API and allows up to 100 characters to be stored. When communicating via the API, values will not be checked against the picklist values that have been configured in the User Interface.

Multiselect fields allow up to 1000 characters to be stored and use double full colons (::) as a delimiter when parsing values to be displayed in the Eloqua UI. These delimiters are converted on external API calls according to the target system.
Large Text Fields are specially designated fields that can contain up to 32K of text. However, in this version of the API, Large Text Fields are not accessible through the API and are not shown in the the description of any objects. This is a planned addition to future versions of the API.
Date Fields store date and time values that can be evaluated against as “before or after” criteria.
Numeric Fields store integer values and allows for the avaluation of criteria such as “greater than” or “less than” and other numeric operators that can be used in filtering.
Number fields are reference numbers to other records in Eloqua. For example a contact has a field called “CompanyID” – this field represents the link to a company in Eloqua.
FIELD META DATA
Field Name is the backend name of the field in Eloqua’s database and is used in all API calls
Display name is the text label shown when this field is displayed within the Eloqua Application UI.
Field Type indicates the type of data that is stored in a field it is returned as a string
Default Value is a string that indicates the value that will automatically populate a record upon creation in Eloqua
Length returns an integer that represents the maximum length of a stored string in a field.
Required is a Boolean value of TRUE/FALSE that determines if a field can remain blank when a record is create dor updated.
Custom is a Boolean value indicated as part of the describe call and shows that a field was created by the user and is not a system generated field.
Writeable is a Boolean value which indicates whether a field can be written or updated via the API.
SECURITY
When logging in, all security aspects are controlled by the UserID that was used to setup the session. Any activity that the user is prohibited from doing through the regular interface will also be prohibited through the API. In this manner the Eloqua Security model remains the same and security groups can effectively bar an API user from logging in via the User Interface if desired.
Eloqua’s API security framework includes the following:
 API calls will only be accepted through a secure HTTPS channel on port 443. These communications are encrypted with Secure Sockets Layer (SSL) for security (minimum 128-bit).
 Access is stateless, and requires authentication for each API call that is sent using a valid username and password that has been placed into a security group that grants access to the API (WS-Security 1.0).
 The same data visibility and access capabilities that apply to users in Eloqua are applied to users connected through the Web services interface. Data visibility and access are restricted by the security groups and asset based security. Permissions are checked for every data access.

 Eloqua employs a variety of security measures and techniques to secure our production network and infrastructure. These same precautions are used for our API infrastructure. These solutions are regularly reviewed and improved as new technologies and techniques become available.
SYSTEM FIELDS
Several fields are included in each entity that are system fields and cannot be written to or updated with a record. These system fields may act as reference fields between objects, or are the EntityID used to identify objects in Eloqua when using the API. These fields are identified as ‘Writable = False’ when using the describeEntity call.
API Call Basics
API calls represent specific operations that your client applications can invoke at runtime to perform tasks. For example:
 Add, update, and delete records in Eloqua
 Query your organization’s information (retrieve calls) (query limit up to 2000 records)
 Bulk retrieve records via API’s bulk data transfer service (no set record limit)
 Using your development environment, you can construct web service client applications that use standard web service protocols to run programmatically
 Create, update, and delete data (using create, update, and delete calls)
 Obtain and navigate metadata about your organization’s data (describeEntity, describeEntityType, describeAsset, describeAssetType, List EntityTypes calls)
 Import and export large datasets using the DataImport and DataExport services
API CALL CHARACTERISTICS
All API calls are:
 Service Requests and Responses—Your application prepares and submits a service request to the Eloqua Web Service via the API, the Web Service processes the request and returns a response, and the client application handles the response.
 Synchronous—When an Eloqua API call is invoked, your client application should wait for a response from the service. The web service does not support asynchronous calls.
 Limited in Length for the results—The return results from queries/retrieve are limited to 2000 records in pages of 20 items. The Bulk Data Transfer service can be used for larger record sets.
 Committed Automatically—Every operation that writes to an Eloqua object is committed automatically. For example, if a client application attempts to create two new Contacts, they are created using mutually- exclusive insert operations that succeed or fail individually, not as a group.
Note: This means that client applications may need to handle some failures.
ERROR HANDLING
When a call is invoked, a failure or success response is always provided. It is imperative that your application be able to handle errors properly, whether returned by the Eloqua API or if because of a

malformed message. Service interruptions and regular maintenance times will return a message indicating that status. Your application should be able to use the return message to handle the error and either re-try or log the situation for manual intervention or troubleshooting:
 For most calls, if the error occurs because of a problem specific to the query, the API returns an Error.
 If an incorrectly-formatted SOAP message is causing the error, an exception is returned by the web service.
See the API Reference area starting on page 22 for more details on Error Messages and how they are returned via the API interface.
Additional Considerations
USAGE METERING
Eloqua provides a limiting infrastructure to make sure that some users do not consume a disproportionate share of the web service infrastructure resources. These limiters constrain customer organizations’ use of server-side resources to equitably share available resources among users and to minimize the possibility of denial-of-service incidents. Eloqua reserves the right to throttle the use of the API at any time to preserve the reliability and operation of the main Eloqua service. The following limitations apply:
 24 hour limit on API calls—As follows:
 Express and Team—Limited to performing X API calls per 24 hour period.
 Enterprise—Limited to performing X API calls per 24 hour period.
 If you require more than these limits on a regular basis please speak with your Account Manager
 Export of Bulk data can be performed on a regular basis but may be throttled or queued depending on load conditions.
 Number of Sessions Limit—Under some circumstances, a server can be flooded with concurrent logins. Eloqua provides session limiters that constrain the number of sessions an organization can have open at any given time. This upper limit on the number of sessions applies to all open Web services sessions.
 Request Rate—All integration requests (data exchange requests) in a session are subject to rate limiting. Rate limiting is implemented for the following reasons:
 A user can perform long-running operations on the server that result in complex and long running queries on the database.
 A user can perform constant operations on the server that constantly use resources.
 Rate limiting can alleviate the previous problems to some extent. Eloqua applies a restriction to each session to limit the number of requests per second that clients can make. The rate limit is set to 1 request every 1 seconds for QUERY calls. Other calls are allowed more often than once per second to a reasonable level.
 InitializeDataExport for data export functions are limited to run every 5 seconds – but generally should not be run on a rapid interval.
 Request Size Limit—The upper limit on the size of any incoming HTTP request is 1MB.
 Maximum Records Returned—For return messages, the maximum number of records returned for each query is limited to 2000. If you exceed the threshold of 2000 records as a result of your query, you will receive an error (with no records returned) and will need to restrict it further so that it returns fewer than 2000 results(ie: add a condition to limit the set). If you need a larger record set than 2000 records, you

will need to perform a bulk data export function which will require you to parse an exported binary file through the SOAP API.
COMPRESSION
HTTP Header compression is used for all outgoing traffic and should be supported by your development environment as this can substantially improve performance versus using an uncompressed HTTP stream.
INTERNATIONAL CHARACTERS
Eloqua’s SOAP encoding allows for UTF-8 character encoding to be passed into the Eloqua system. Eloqua fully supports UTF-8 character encoding in most fields natively. You need to ensure that you are passing the values in their original encoding.
ELOQUA IDENTIFICATION CODES
Eloqua uses a series of unique IDs for each record in the system that is generated server-side for each unique record. The API calls use these ID’s exclusively for executing their functionality. If there is a situation where you require the ID of another entity, there are a variety of different ways of getting that information. For example if you are given an email address to update a record, a query looking for a record with the matching email address will return a Contact ID. This ID can then be used to update the record.
It is recommended that you create a Foreign ID field in your CRM to store the Eloqua Contact ID as it will be used for all update sto the Eloqua database.
API Reference
METADATA
The metadata that describes the attributes and properties of objects in your Eloqua database is accessible through describe calls. These methods allow you to discover information about Entities and Assets in your system. Note that this information is read-only.
ENTITY METADATA
An Entity is an abstract representation of an object in Eloqua, such as a Contact, Company or Data Card Set. Entity objects can have attributes. For example: A Contact entity has an Email Address and a First Name.
The web service contains operations for discovering all the entities and entity types in the system as well as the metadata information for each entity. The following operations are available:

ENTITY METADATA OPERATIONS
ListEntityTypes
Usage
Retrieve all the entity types in your Eloqua database. This includes the Base type that contains the Contact and Company entities. Only types available in the instance of Eloqua which you are logged into are returned. Your application can parse the response and query for further information such as the metadata for each Entity type.
Arguments
None
Response
ListEntityTypesResult
Faults
UnexpectedErrorFault
Syntax
Service instance; ListEntityTypesResult returnValue;
returnValue = instance.ListEntityTypes();

Sample Code - .NET
Sample Code – Java
try
{
// Set up the Eloqua API Service
EloquaService.EloquaServiceClient service = new EloquaService.EloquaServiceClient();
service.ClientCredentials.UserName.UserName = "Companydefault.user";
service.ClientCredentials.UserName.Password = "test123";
// Execute the request
EloquaService.ListEntityTypesResult result = service.ListEntityTypes();
// Extract the name of each Entity Type
foreach (String entityType in result.EntityTypes)
{
Console.WriteLine(entityType);
}
}
catch (System.ServiceModel.FaultException ex)
{
// Customize your own Error handling code.
Console.WriteLine(String.Format("Reson: {0}", ex.Reason.ToString()));
Console.WriteLine(String.Format("Fault Type: {0}", ex.GetType().ToString()));
Console.WriteLine(String.Format("Fault Code: {0}", ex.Code.Name.ToString()));
}
catch (Exception ex)
{
Console.WriteLine(String.Format("Exception Message: {0}", ex.Message.ToString()));
}
try
{
EloquaService.Eloqua eloquaService = new EloquaService.Eloqua();
EloquaService.EloquaService service = eloquaService.getEloquaService();
EloquaService.ListEntityTypesResult result = service.listEntityTypes();
// Extract the name of each Entity Type
for (String entityType : result.getEntityTypes().getValue().getString())
{
System.out.println(entityType);
}
}
catch (Javax.xml.ws.soap.SOAPFaultException ex)
{
System.out.println(String.format("Message: %s", ex.getMessage()));
System.out.println(String.format("Fault Code: %s", ex.getFault().getFaultCode()));
}
{
System.out.println(ex.getMessage());
}

See Also
DescribeEntityType DescribeEntity WSDL Information
DescribeEntityType
Usage
Retrieve a list of all the entities in a given Entity Type. For example: Contacts, Companies and Prospects are entities contained in the Base Entity Type.
Arguments
entityType (String)
Response
DescribeEntityTypeResult
Faults
UnexpectedErrorFault ValidationFault InvalidTypeFault
Syntax
Service instance; String entityName;
DescribeEntityTypeResult returnValue; returnValue = instance.DescribeEntityType(entityType);

Sample Code - .NET
try
{
EloquaService.DescribeEntityTypeResult result = service.DescribeEntityType("Base");
// Extract the ID, Name and Type of each Entity in the Base Type
foreach (EloquaService.EntityType entityType in result.EntityTypes)
{
Console.WriteLine(String.Format("ID: {0}", entityType.ID));
Console.WriteLine(String.Format("Type: {0}", entityType.Type));
Console.WriteLine(String.Format("Name: {0}", entityType.Name));
}
}
{
}
{
}
try
{
EloquaService.DescribeEntityTypeResult result = service.describeEntityType("Base");
// Extract the ID, Name and Type of each Entity Type
for (EloquaService.EntityType entityType : result.getEntityTypes().getValue().getEntityType())
{
System.out.println(String.format("ID: %s", String.valueOf(entityType.getID())));
System.out.println(String.format("Name %s", entityType.getName().getValue()));
System.out.println(String.format("Type: %s", entityType.getType().getValue()));
}
}
{
}
{
}

See Also
DescribeEntity ListEntityTypes WSDL Information
DescribeEntity
Usage
Retrieve all the metadata for a specific Entity. The information returned also contains access permissions on the entity (Readable, Createable, etc…)
Arguments
entityType (EntityType)
Response
DescribeEntityResult
Faults
Syntax
Service instance; EntityType entityType;
DescribeEntityResult returnValue; returnValue = instance.DescribeEntity (entityType);

Sample Code - .NET
try
{
// Define a Contact Entity Type object
EloquaService.EntityType entityType = new EloquaService.EntityType();
entityType.ID = 0;
entityType.Name = "Contact";
entityType.Type = "Base";
EloquaService.DescribeEntityResult result = service.DescribeEntity(entityType);
// Extract the Entity's Name
Console.WriteLine(String.Format("Entity Name: {0}", result.Name));
// Extract the Entity's Properties
Console.WriteLine(String.Format("Is Createable: {0}", result.IsCreateable));
Console.WriteLine(String.Format("Is Deletable: {0}", result.IsDeletable));
Console.WriteLine(String.Format("Is Queryable: {0}", result.IsQueryable));
Console.WriteLine(String.Format("Is Retrievable: {0}", result.IsRetrievable));
Console.WriteLine(String.Format("Is Updateable: {0}", result.IsUpdateable));
// Extract the Entity's Field Metadata
foreach (EloquaService.DynamicEntityFieldDefinition fieldDef in result.Fields)
{
Console.WriteLine(String.Format("Data Type: {0}", fieldDef.DataType));
Console.WriteLine(String.Format("Default Value: {0}", fieldDef.DefaultValue));
Console.WriteLine(String.Format("Display Name: {0}", fieldDef.DisplayName));
Console.WriteLine(String.Format("Internal Name: {0}", fieldDef.InternalName));
Console.WriteLine(String.Format("Is Custom: {0}", fieldDef.IsCustom));
Console.WriteLine(String.Format("Is Required: {0}", fieldDef.IsRequired));
Console.WriteLine(String.Format("Is Writeable: {0}", fieldDef.IsWriteable));
Console.WriteLine(String.Format("Length: {0}", fieldDef.Length));
}
}
{
}
{
}

See Also
DescribeEntityType ListEntityTypes WSDL Information
try
{
// Instantiate a new Eloqua Service object factory
EloquaService.ObjectFactory serviceFactory = new EloquaService.ObjectFactory();
entityType.setID(0);
entityType.setName(serviceFactory.createEntityTypeName("Contact"));
entityType.setType(serviceFactory.createEntityTypeType("Base"));
EloquaService.DescribeEntityResult result = service.describeEntity(entityType);
// Extract the Entity's Properties
System.out.println(String.format("Is Createable: %s", result.isIsCreateable()));
System.out.println(String.format("Is Deleteable: %s", result.isIsDeletable()));
System.out.println(String.format("Is Queryable: %s", result.isIsQueryable()));
System.out.println(String.format("Is Retrievable: %s", result.isIsRetrievable()));
System.out.println(String.format("Is Updateable: %s", result.isIsUpdateable()));
// Extract the Entity's Field Metadata
for (EloquaService.DynamicEntityFieldDefinition fieldDef : result.getFields().getValue().getDynamicEntityFieldDefinition())
{
System.out.println(String.format("Data Type: %s", fieldDef.getDataType().value()));
System.out.println(String.format("Default Value: %s", fieldDef.getDefaultValue().getValue()));
System.out.println(String.format("Display Name: %s", fieldDef.getDisplayName().getValue()));
System.out.println(String.format("Internal Name: %s", fieldDef.getInternalName().getValue()));
System.out.println(String.format("Is Custom: %s", fieldDef.isIsCustom()));
System.out.println(String.format("Is Required: %s", fieldDef.isIsRequired()));
System.out.println(String.format("Is Writeable: %s", fieldDef.isIsWriteable()));
System.out.println(String.format("Length: %s", String.valueOf(fieldDef.getLength())));
}
}
{
}
{
}

ENTITY OPERATIONS
This section describes the operations that can be performed to retrieve and change an Entity’s data using the API. When performing an operation it is important to use the Eloqua ID of the object you are attempting to modify or delete. The following operations are available for most Entities (Visitor Profiles and Forms are read-only):
Create
Usage
Create one or more new Entities in the Eloqua database.
Arguments
dynamicEntity[]
Response
CreateResult[]
Faults
UnexpectedErrorFault ValidationFault InvalidTypeFault BatchSizeExceededFault
Syntax
Service instance; DynamicEntity[] dynamicEntities;
CreateResult[] returnValue; returnValue = instance.Create(dynamicEntities);

Sample Code - .NET
Note: .NET code sample concluded on next page.
try
{
// Build a Contact Entity Type object
entityType.ID = 0;
// Create a new Array of Dynamic Entities
EloquaService.DynamicEntity[] dynamicEntities = new EloquaService.DynamicEntity[1];
// Create a new Dynamic Entity and add it to the Array of Entities
dynamicEntities[0] = new EloquaService.DynamicEntity();
dynamicEntities[0].EntityType = entityType;
// Create a Dynamic Entity's Field Value Collection
dynamicEntities[0].FieldValueCollection = new EloquaService.DynamicEntityFields();
// Add the Contact's Email Address field to the Dynamic Entity’s field collection
dynamicEntities[0].FieldValueCollection.Add("C_EmailAddress", "support@eloqua.com");
// Add the Contact's First Name field to the Dynamic Entity’s field collection
dynamicEntities[0].FieldValueCollection.Add("C_FirstName", "Support");
EloquaService.CreateResult[] result = service.Create(dynamicEntities);
// Verify the status of each Contact Create request in the results
for (int i = 0; i < result.Length; i++)
{
// Successfull requests return a positive integer value for ID
if (result[i].ID != -1)
{
Console.WriteLine("Success");
}
// Failed requests return a -1 integer value for ID
else
{
Console.WriteLine("Failure");
// Extract the Error Message and Error Code for each failed Create request
foreach (EloquaService.Error createError in result[i].Errors)
{
Console.WriteLine(String.Format("Code: {0}", createError.ErrorCode));
Console.WriteLine(String.Format("Message: {0}", createError.Message));
}
}
}
}

Sample Code - .NET (continued)
Note: Java code sample concluded on next page.
{
}
{
}
try
{
EloquaService.ArrayOfDynamicEntity dynamicEntities = new EloquaService.ArrayOfDynamicEntity();
EloquaService.DynamicEntity dynamicEntity = new EloquaService.DynamicEntity();
dynamicEntity.setEntityType(serviceFactory.createEntityType(entityType));
EloquaService.DynamicEntityFields fieldValueCollection = new EloquaService.DynamicEntityFields();
fieldValueCollection = serviceFactory.createDynamicEntityFields();
// Add the Contact's Email Address field to the Dynamic Entity’s field collection
EloquaService.DynamicEntityFields.EntityFields emailField = serviceFactory.createDynamicEntityFieldsEntityFields();
emailField.setInternalName("C_EmailAddress");
emailField.setValue("support@eloqua.com");
fieldValueCollection.getEntityFields().add(emailField);
// Add the Contact's First Name field to the Dynamic Entity’s field collection
EloquaService.DynamicEntityFields.EntityFields firstNameField = serviceFactory.createDynamicEntityFieldsEntityFields();
firstNameField.setInternalName("C_FirstName");
firstNameField.setValue("Support");
fieldValueCollection.getEntityFields().add(firstNameField);

Sample Code – Java (continued)
See Also
Retrieve Update Delete Query WSDL Information
// Add the Dynamic Fields to the Dynamic Entitiy
JAXBElement<EloquaService.DynamicEntityFields> fc;
fc = serviceFactory.createDynamicEntityFieldValueCollection(fieldValueCollection);
dynamicEntity.setFieldValueCollection(fc);
// Add the Dynamic Entity (Contact) to the Array of Dynamic Entities
dynamicEntities.getDynamicEntity().add(dynamicEntity);
EloquaService.ArrayOfCreateResult result = service.create(dynamicEntities);
// Verify the status of each Contact Create request in the results
for (int i = 0; i < result.getCreateResult().size(); i++)
{
if (result.getCreateResult().get(i).getID() != -1)
{
System.out.println("Success");
}
else
{
System.out.println("Failure");
// Extract the Error Message and Error Code for each failed Create request
for (EloquaService.Error createError : result.getCreateResult().get(i).getErrors().getValue().getError())
{
System.out.println(createError.getErrorCode().value());
System.out.println(createError.getMessage().getValue());
}
}
}
}
{
}
{
}

Retrieve
Usage
Retrieve one or more Entities from the Eloqua database.
Arguments
EntityType id[] (Integer) String[] fieldList
Response
RetrieveResult[]
Faults
Syntax
Service instance; EntityType entityType; int[] ids; String[] fieldList;
DynamicEntity[] returnValue; returnValue = instance.Retrieve(entityType, ids, fieldList);

Sample Code - .NET
try
{
entityType.ID = 0;
// Set the ID of the Contact Entity
int[] ids = new int[1];
ids[0] = 1200846;
// Create a new list containing the fields you want populated
List<string> fieldList = new List<string>();
// Add the Contact’s Email Address to the field list
fieldList.Add("C_EmailAddress");
// Add the Contact’s First Name to the field list
fieldList.Add("C_FirstName");
// Build a Dynamic Entity array to store the results
EloquaService.DynamicEntity[] retrievedEntities;
// If the field list is empty - the request will return all Entity Fields
// Otherwise, only fields defined in the field list are returned
if (fieldList.Count == 0)
{
// Execute the request and return all of the Entity's fields
retrievedEntities = service.Retrieve(entityType, ids, null);
}
else
{
// Execute the request and return only the selected Entity fields
retrievedEntities = service.Retrieve(entityType, ids, fieldList.ToArray());
}
// If a result was found, extract the field values for each Dynamic Entity
if (retrievedEntities.Length > 0)
{
foreach (EloquaService.DynamicEntity dynamicEntity in retrievedEntities)
{
// Extract the Field Name and Value for each element in the collection
foreach (KeyValuePair<string, string> keyValPair in dynamicEntity.FieldValueCollection)
{
Console.WriteLine(String.Format("Field Name: {0}", keyValPair.Key));
Console.WriteLine(String.Format("Field Value: {0}", keyValPair.Value));
}
}
}
}

Note: Java code sample concluded on next page.
{
}
{
}
try
{
// Set the ID of the Contact Entity
EloquaService.ArrayOfint ids = new EloquaService.ArrayOfint();
ids.getInt().add(1200846);
// Create a new array containing the fields you want populated for this Entity
EloquaService.ArrayOfstring fieldList = new EloquaService.ArrayOfstring();
// Add the Contact’s Email Address to the field list
fieldList.getString().add("C_EmailAddress");
// Add the Contact’s First Name to the field list
fieldList.getString().add("C_FirstName");
// Build a Dynamic Entity array to store the results
EloquaService.ArrayOfDynamicEntity retrievedEntities;
// If the field array is empty - the request will return all Entity Fields
if (fieldList.getString().size() == 0)
{
retrievedEntities = service.retrieve(entityType, ids, null);
}
else
{
retrievedEntities = service.retrieve(entityType, ids, fieldList);
}

See Also
Create Update Delete Query WSDL Information
Update
Usage
Update one or more Entities in the Eloqua database.
Arguments
dynamicEntity[]
Response
UpdateResult[]
Faults
// If a result was found, extract the field values for each Dynamic Entity
if (retrievedEntities.getDynamicEntity().size() > 0)
{
for (EloquaService.DynamicEntity dynamicEntity : retrievedEntities.getDynamicEntity())
{
// Extract the Field Name and Value for each element in the collection
for (EloquaService.DynamicEntityFields.EntityFields field : dynamicEntity.getFieldValueCollection().getValue().getEntityFields())
{
System.out.println(String.format("Field Name: %s", field.getInternalName()));
System.out.println(String.format("Field Value: %s", field.getValue()));
}
}
}
}
{
}
{
}

Syntax
Sample Code - .NET
Service instance; DynamicEntity[] dynamicEntities;
UpdateResult[] returnValue; returnValue = instance.Update(dynamicEntities);
try
{
entityType.ID = 0;
EloquaService.DynamicEntity[] dynamicEntities = new EloquaService.DynamicEntity[1];
dynamicEntities[0] = new EloquaService.DynamicEntity();
// Set the Entity Type to Contact
dynamicEntities[0].EntityType = entityType;
// Set the Contact record's ID
dynamicEntities[0].Id = 1;
dynamicEntities[0].FieldValueCollection = new EloquaService.DynamicEntityFields();
// Add the Contact's Email Address to the Dynamic Entity's field collection
dynamicEntities[0].FieldValueCollection.Add("C_EmailAddress", "support@eloqua.com");
// Add the Contact's First Name to the Dynamic Entity's field collection
dynamicEntities[0].FieldValueCollection.Add("C_FirstName", "Support");
EloquaService.UpdateResult[] result = service.Update(dynamicEntities);

Note: Java code sample continued on next page.
// Verify the status of each Contact Update request in the results
for (int i = 0; i < result.Length; i++)
{
if (result[i].ID != -1)
{
}
else
{
// Extract the Error Message and Error Code for each failed Update request
foreach (EloquaService.Error updateError in result[i].Errors)
{
Console.WriteLine(String.Format("Code: {0}", updateError.ErrorCode));
Console.WriteLine(String.Format("Message: {0}", updateError.Message));
}
}
}
}
{
}
{
}
try
{
EloquaService.ArrayOfDynamicEntity dynamicEntities = new EloquaService.ArrayOfDynamicEntity();

Note: Java code sample conclued on next page.
// Instantiate a new Dynamic Entity
EloquaService.DynamicEntity dynamicEntity = new EloquaService.DynamicEntity();
dynamicEntity.setEntityType(serviceFactory.createEntityType(entityType));
EloquaService.DynamicEntityFields fieldValueCollection = new EloquaService.DynamicEntityFields();
fieldValueCollection = serviceFactory.createDynamicEntityFields();
// Add the Contact's Email Address to the Dynamic Entity's field collection
EloquaService.DynamicEntityFields.EntityFields emailField = serviceFactory.createDynamicEntityFieldsEntityFields();
emailField.setInternalName("C_EmailAddress");
emailField.setValue("support@eloqua.com");
fieldValueCollection.getEntityFields().add(emailField);
// Add the Contact's First Name to the Dynamic Entity's field collection
EloquaService.DynamicEntityFields.EntityFields firstNameField = serviceFactory.createDynamicEntityFieldsEntityFields();
firstNameField.setInternalName("C_FirstName");
firstNameField.setValue("Support");
fieldValueCollection.getEntityFields().add(firstNameField);
// Add the Dynamic Entity's fields to the Dynamic Entitiy's field collection
JAXBElement<EloquaService.DynamicEntityFields> fc;
fc = serviceFactory.createDynamicEntityFieldValueCollection(fieldValueCollection);
dynamicEntity.setFieldValueCollection(fc);
// Add the Dynamic Entity (Contact) to the Array of Dynamic Entities
dynamicEntities.getDynamicEntity().add(dynamicEntity);
EloquaService.ArrayOfUpdateResult result = service.update(dynamicEntities);
// Verify the status of each Contact Update request in the results
for (int i = 0; i < result.getUpdateResult().size(); i++)
{
if (result.getUpdateResult().get(i).getID() != -1)
{
}
else
{
// Extract the Error Message and Error Code for each failed Update request
for (EloquaService.Error UpdateError : result.getUpdateResult().get(i).getErrors().getValue().getError())
{
System.out.println(UpdateError.getErrorCode().value());
System.out.println(UpdateError.getMessage().getValue());
}
}
}
}

See Also
Create Retrieve Delete Query WSDL Information
Delete
Usage
Delete one or more Entities in the Eloqua database.
Arguments
EntityType id[] (Integer)
Response
DeleteResult[]
Faults
Syntax
{
}
{
}
Service instance; entityType entityType; int[] ids;
DeleteResult[] returnValue; returnValue = instance.Delete(entityType, ids);

Sample Code - .NET
try
{
entityType.ID = 0;
// Set the ID of each Entity that you want to delete
int[] ids = new int[1];
ids[0] = 1;
EloquaService.DeleteResult[] deleteResults = service.Delete(entityType, ids);
// Verify the status of each Delete request in the results
for (int i = 0; i <= deleteResults.Length - 1; i++)
{
// Successfull requests will return a positive integer value for ID
if (deleteResults[i].Success)
{
}
// Failed requests will return a -1 integer value for ID
else
{
// Extract the Error Message and Error Code for each failed Delete request
foreach (EloquaService.Error deleteError in deleteResults[i].Errors)
{
Console.WriteLine(String.Format("Code: {0}", deleteError.ErrorCode));
Console.WriteLine(String.Format("Message: {0}", deleteError.Message));
}
}
}
}
{
}
{
}

try
{
// Set the ID of each Entity that you want to delete
EloquaService.ArrayOfint ids = new EloquaService.ArrayOfint();
ids.getInt().add(1);
EloquaService.ArrayOfDeleteResult deleteResults = service.delete(entityType, ids);
// Verify the status of each Delete request in the results
for (int i = 0; i <= deleteResults.getDeleteResult().size(); i++)
{
if (deleteResults.getDeleteResult().get(i).isSuccess())
{
}
else
{
// Extract the Error Message and Error Code for each failed Delete request
for (EloquaService.Error deleteError : deleteResults.getDeleteResult().get(i).getErrors().getValue().getError())
{
System.out.println(String.format("Code: %s", deleteError.getErrorCode().value()));
System.out.println(String.format("Message: %s", deleteError.getMessage().getValue()));
}
}
}
}
{
}
{
}

See Also
Create Retrieve Update Query WSDL Information
Query
Usage
Query one or more Entities from the Eloqua database.
Syntax
<SEARCH_TERM> <OPERATOR> ‘<VALUE>’ AND ‘<VALUE>’ Search Term—The field to search for, represented by a string with no spaces.
Value—The value to search for, represented by a string enclosed in quotes. This value can include the wildcard: *
Boolean (AND) Operator—An optional Boolean operator equivalent to an intersection of the 2 search values (see the List of Operators below).
Note: If you query the database and the resultset is greater than 2000 records, an error will be returned(with no records). Your query needs to be adjusted to return fewer than 2000 records before you will receive any results. You can page through the results 20 results at a time. Should you require a larger set of results, you could setup a bulk download via the API. List of Operators: Operator Query Syntax
Equal To
=
Not Equal To
-
Greater Than
>
Less Than
<
Greater Than or Equal To
>=
Less Than or Equal To
<=
Arguments
EntityType[] searchQuery (String) fieldnames[] (String[]) pageNumber (Integer) pageSize (Integer)

Response
DynamicEntityQueryResults
Faults
UnexpectedErrorFault ValidationFault InvalidTypeFault QueryTooLargeFault InvalidQueryFault OperationTimeIntervalFault
Syntax
Sample Code - .NET
Service instance; entityType entityType; String searchQuery; String[] fieldnames; int pageNumber; int pageSize;
queryResult[] returnValue; returnValue = instance.Query(entityType, searchQuery, fieldList, pageNumber, pageSize);
try
{
entityType.ID = 0;
List<string> fieldList = new List<string>();
// Add the Contact's Email Address to the field list
fieldList.Add("C_EmailAddress");
// Add the Contact's First Name to the field list
fieldList.Add("C_FirstName");
// Build the Search Query
String queryText = "C_EmailAddress ='*@eloqua.com'";
// Define a container for the Query results
EloquaService.DynamicEntityQueryResults queryResult;

// Set the page number and size for the results
int currentPage = 0;
int pageSize = 20;
if (fieldList.Count == 0)
{
queryResult = service.Query(entityType, queryText, null, currentPage, pageSize);
}
else
{
queryResult = service.Query(entityType, queryText, fieldList.ToArray(), currentPage, pageSize);
}
if (queryResult.Entities.Length > 0)
{
// Extract the total number of pages and records
Console.WriteLine(String.Format("Total number of pages: {0}", queryResult.TotalPages.ToString()));
Console.WriteLine(String.Format("Total number of records: {0}", queryResult.TotalRecords.ToString()));
// Extract each Dynamic Entity in the result
foreach (EloquaService.DynamicEntity dynamicEntity in queryResult.Entities)
{
// Extract the Entity ID
Console.WriteLine(String.Format("Entity ID: {0}", dynamicEntity.Id));
// Extract the field name and value of each field in the collection
foreach (KeyValuePair<string, string> field in dynamicEntity.FieldValueCollection)
{
Console.WriteLine(String.Format("Field Name: {0}", field.Key));
Console.WriteLine(String.Format("Field Value: {0}", field.Value));
}
}
}
}
{
}
{
}

Note: Java code sample conclued on next page.
try
{
Java.util.List<String> fieldList = new Java.util.ArrayList<String>();
// Add the Contact's Email Address to the field list
fieldList.add("C_EmailAddress");
// Add the Contact's First Name to the field list
fieldList.add("C_FirstName");
// Build the Search Query
String queryText = "C_EmailAddress ='*@eloqua.com'";
// Build a new container for the Query results
EloquaService.DynamicEntityQueryResults queryResult;
// Set the page number and size for the results
int currentPage = 0;
int pageSize = 20;
// Otherwize, only fields defined in the field list are returned
if (fieldList.size() == 0)
{
queryResult = service.query(entityType, queryText, null, pageSize, pageSize);
}
else
{
// Execute the request and return only the selected fields
queryResult = service.query(entityType, queryText, null, pageSize, pageSize);
}
if (queryResult.getEntities().getValue().getDynamicEntity().size() > 0)
{
// Extract the total number of pages and records
System.out.println(String.format("Total number of pages: %s", queryResult.getTotalPages()));
System.out.println(String.format("Total number of records: %s", queryResult.getTotalRecords()));

See Also
Create Retrieve Update Delete WSDL Information
ASSET METADATA
An Asset is an abstract representation of structured data in Eloqua, such as an Email Brochure or Data Export. Assets can have attributes. Examples: An Email Brochure has a Subject and Body. DataImports have a title and an ID.
The web service contains operations for discovering all the assets and asset types in the system. The following operations are available:
1. ListAssetTypes()
This function will return a list of the currently accessible AssetTypes from within your instance of Eloqua which can then be used as a parameter for DescribeAssetType.
2. DescribeAssetType()
This will return attributes of the AssetType that you specify
// Extract each Dynamic Entity in the result
for (EloquaService.DynamicEntity dynamicEntity : queryResult.getEntities().getValue().getDynamicEntity())
{
// Extract the Entity ID
System.out.println(String.format("Entity ID: %s", dynamicEntity.getId()));
// Extract the field name and value of each field in the collection
for (EloquaService.DynamicEntityFields.EntityFields field : dynamicEntity.getFieldValueCollection().getValue().getEntityFields())
{
System.out.println(String.format("Field Name: %s", field.getInternalName()));
System.out.println(String.format("Field Value: %s", field.getValue()));
}
}
}
}
{
}
{
}

ASSET METADATA OPERATIONS
ListAssetTypes
Usage
Retrieve all the Asset Types in your Eloqua database. Only Types available in the instance of Eloqua which you are logged into are returned. Your application can parse the response and query for further information such as the metadata for each Asset Type.
Arguments
None
Response
ListAssetTypeResult
Faults
UnexpectedErrorFault
Syntax
Service instance; ListAssetTypesResult returnValue;
returnValue = instance.ListAssetTypes();

Sample Code - .NET
try
{
EloquaService.ListAssetTypesResult result = service.ListAssetTypes();
// Extract the name of each Asset Type
foreach (String AssetType in result.AssetTypes)
{
Console.WriteLine(AssetType);
}
}
{
}
{
}
try
{
EloquaService.ListAssetTypesResult result = service.listAssetTypes();
// Extract the name of each Asset Type
for (String assetType : result.getAssetTypes().getValue().getString())
{
System.out.println(assetType);
}
}
{
}
{
}

See Also
DescribeAssetType WSDL Information
DescribeAssetType
Usage
Retrieve all the Assets in a given Asset Type.
Arguments
assetType (String)
Response
DescribeAssetTypeResult
Faults
Syntax
Service instance; String entityName;
DescribeAssetTypeResult returnValue; returnValue = instance.DescribeAssetType(assetType);

Sample Code - .NET
try
{
EloquaService.DescribeAssetTypeResult result = service.DescribeAssetType("DataExport");
// Extract the ID, Name and Type of each Asset Type
foreach (EloquaService.AssetType AssetType in result.AssetTypes)
{
Console.WriteLine(String.Format("ID: {0}", AssetType.ID));
Console.WriteLine(String.Format("Type: {0}", AssetType.Type));
Console.WriteLine(String.Format("Name: {0}", AssetType.Name));
}
}
{
}
{
}

See Also
ListAssetTypes WSDL Information
Data Transfer Service
The Data Transfer service has also been referred to as “Bulk” data transfers in this guide. The data transfer service allows for the updating of large numbers of records within Eloqua in a scalable fashion. It also allows for bulk transfer of data from Eloqua to a streamlined file for download and manipulation. The data transfer service is the preferred method of transferring records if the number of records will regularly exceed 2000 records as this is the current limit for any queries into the Eloqua system through the web services API.
The Data Export service will allow the export via the API of any saved report in the system that returns a list of Contact, Prospect or Company entity records. It will also allow for the export of static reports that contain contact activity data:
try
{
EloquaService.DescribeAssetTypeResult result = service.describeAssetType("DataImport");
// Extract the ID, Name and Type of each Asset Type
for (EloquaService.AssetType assetType : result.getAssetTypes().getValue().getAssetType())
{
System.out.println(String.format("ID: %s", String.valueOf(assetType.getID())));
System.out.println(String.format("Name %s", assetType.getName().getValue()));
System.out.println(String.format("Type: %s", assetType.getType().getValue()));
}
}
{
}
{
}

Running an export via the API will first trigger the Eloqua server to produce a Report and export it to a flat file on our servers. This flat file can then be transferred via the API as a binary transfer to your web service. The web service on your end is then responsible for parsing or transferring the contents of the file.
Running an import of a file must first be setup within the Eloqua User Interface to specify the following settings into an “AutoSynch”: Field mappings, actions to perform after upload, notification of success or failure. When importing via the API, you will need to specify the ID of one of these previously saved “AutoSynchs” to be used when importing your file.
The Data Transfer services use the following WSDL:
https://secure.eloqua.com/API/1.2/DataTransferService.svc?wsdl
Data Transfer Services support bulk transfer of flat files through the API. This particular API endpoint has been optimized for transmitting binary files.
Note: Only Reports that are regular Contact/Prospect/Company record type of Reports are exportable through the data transfer service. Some saved Reports will not be visible via the API because they are not one of these standard types (ie: visitor reports).
DATA EXPORT OPERATIONS
Before you can export data through the bulk export system you will need to login to the Eloqua UI and create some standard data extracts that you will be performing. You will need to create a “saved report” within Eloqua – and then setup that saved report for export. Once that is performed – the newly created export report will be shown when describing the DataIExport Assets via the API.
The following Data Export operations are available:
InitializeDataExport
Usage
Initialize a Data Export.

Arguments
AssetType
Response
DataExportExecution
Faults
UnexpectedErrorFault ValidationFault OperationTimeIntervalFault
Syntax
Sample Code - .NET
Service instance; AssetType assetType;
instance.InitializeDataExport(assetType);
try
{
// Set up the Eloqua API Data Transfer Service
EloquaDataService.DataTransferServiceClient service = new EloquaDataService.DataTransferServiceClient();
service.ClientCredentials.UserName.UserName = "Eloquaapi.user";
// Build an Asset Type object
EloquaDataService.AssetType assetType = new EloquaDataService.AssetType();
assetType.ID = 0;
assetType.Name = "Sample Data Export";
assetType.Type = "DataExport";
service.InitializeDataExport(assetType);
// Extract the ID of the Data Export Execution
Console.WriteLine(String.Format("Data Export Initialized"));
}
{
}
{
}

See Also
DataExportStatus GetDataExportFile WSDL Information
try
{
EloquaDataService.EloquaDataTransfer eloquaService = new EloquaDataService.EloquaDataTransfer();
EloquaDataService.DataTransferService service = eloquaService.getEloquaDataTransferService();
// Instantiate a new Eloqua Data Transfer Service object factory
EloquaDataService.ObjectFactory serviceFactory = new EloquaDataService.ObjectFactory();
// Build an Asset Type object
assetType.setID(0);
assetType.setName(serviceFactory.createAssetTypeName("Sample Data Export"));
assetType.setType(serviceFactory.createAssetTypeType("DataExport"));
service.initializeDataExport(assetType);
// Extract the ID of the Data Export Execution
System.out.println(String.format("Data Export Initialized",));
}
{
}
{
}

DataExportStatus
Usage
Retrieve the status of a Data Export execution.
Arguments
AssetType
Response
DataExportExecutionStatus
Faults
UnexpectedErrorFault ValidationFault
Syntax
Service instance; AssetType assetType; DataExportExecutionStatus returnValue; returnValue = instance.DataExportStatus(assetType);

Sample Code - .NET
try
{
// Build a Data Export Asset Type object
assetType.ID = 0;
EloquaDataService.DataExportExecutionStatus status = service.DataExportStatus(assetType);
// Extract the status of the Data Export
switch (status)
{
case SampleCode.EloquaDataService.DataExportExecutionStatus.Complete:
Console.WriteLine("Data Export is Complete");
break;
case SampleCode.EloquaDataService.DataExportExecutionStatus.Failure:
Console.WriteLine("Data Export Failed");
break;
case SampleCode.EloquaDataService.DataExportExecutionStatus.InProgress:
Console.WriteLine("Data Export in Progress");
break;
}
}
{
}
{
}

See Also
InitializeDataExport GetDataExportFile WSDL Information
GetDataExportFile
Usage
Retrieve the Data Export file.
Arguments
AssetType
try
{
assetType.setID(0);
EloquaDataService.DataExportExecutionStatus status = service.dataExportStatus(assetType);
// Extract the status of the Data Export
switch (status)
{
case COMPLETE:
System.out.println("Data Export is Complete");
case FAILURE:
System.out.println("Data Export Failed");
case IN_PROGRESS:
System.out.println("Data Export in Progress");
}
}
{
}
{
}

Response
Byte[]
Faults
Syntax
Service instance; AssetType assetType; Byte[] returnValue; returnValue = instance.GetDataExportFile(assetType);

Sample Code - .NET
try
{
assetType.ID = 0;
Byte[] byteData = service.GetDataExportFile(assetType);
// Define the file and filestream
String fileName = "c:fileName.txt";
System.IO.FileStream ioFileStream = null;
// Try writing the bytes to a file
try
{
// Instatiate a new file stream
ioFileStream = new System.IO.FileStream(fileName, System.IO.FileMode.Create);
// Try writing the bytes to the file
ioFileStream.Write(byteData, 0, byteData.Length);
}
{
throw new System.Exception(String.Format("Unable to create file {0}", fileName));
}
finally
{
// Close the file stream
ioFileStream.Close();
}
}
{
}
{
}

See Also
InitializeDataExport DataExportStatus WSDL Information
try
{
assetType.setID(0);
byte[] bytes = service.getDataExportFile(assetType);
// Define the file
// Try writing the bytes to a file
try
{
// Instantiate a new file stream
Java.io.FileOutputStream fileOutputStream = new Java.io.FileOutputStream(fileName);
// Try writing the bytes to the file
fileOutputStream.write(bytes);
// Close the file stream
fileOutputStream.close();
}
{
throw new Exception(String.format("Unable to create file %s", fileName));
}
}
{
}
{
}

DATA IMPORT OPERATIONS
The following Data Import operations are available:
InitializeDataImport
Usage
Initialize a Data Import.
Arguments
Byte[] AssetType DataSourceType
Response
DataImportExecution
Faults
UnexpectedErrorFault ValidationFault InvalidFileType QueueLimitReachedFault
Syntax
Service instance; Byte[] data; AssetType assetType; DataSourceType dataSourceType;
Byte[] returnValue; returnValue = instance.InitializeDataImport(data, assetType, dataSourceType);

Sample Code - .NET
try
{
// Build a Data Import Asset Type object
assetType.ID = 0;
assetType.Name = "Sample Data Import";
assetType.Type = "DataImport";
// Select a Delimited file for the Data Source Type
EloquaDataService.DataSourceType dataSourceType = SampleCode.EloquaDataService.DataSourceType.DelimitedFile;
// Set the filename
// Instantiate a new file and binary reader
FileInfo fileInfo = new FileInfo(fileName);
BinaryReader binaryReader = new BinaryReader(new FileStream(fileName, FileMode.Open, FileAccess.Read));
// Read the file into a Byte array
Byte[] data = binaryReader.ReadBytes(Convert.ToInt32(fileInfo.Length));
// Close the binary reader
binaryReader.Close();
EloquaDataService.DataImportExecution dataImportExecution = service.InitializeDataImport(data, assetType, dataSourceType);
// Extract the ID of the Data Import Execution
Console.WriteLine(String.Format("Data Import Execution ID: {0}", dataImportExecution.ID.ToString()));
}
{
}
{
}

try
{
assetType.setID(0);
assetType.setName(serviceFactory.createAssetTypeName("Sample Data Import"));
assetType.setType(serviceFactory.createAssetTypeType("DataImport"));
// Select a Delimited file for the Data Source Type
EloquaDataService.DataSourceType dataSourceType = EloquaDataService.DataSourceType.DELIMITED_FILE;
// Set the filename
Java.io.File file = new Java.io.File(fileName);
// Instantiate a new input stream
Java.io.InputStream is = new Java.io.FileInputStream(fileName);
byte[] byteData = new byte[(int) file.length()];
// Read the bytes to file
int offset = 0;
int numRead = 0;
while (offset < file.length() && (numRead=is.read(byteData, offset, byteData.length-offset)) >= 0)
{
offset += numRead;
}
EloquaDataService.DataImportExecution dataImportExecution = service.initializeDataImport(byteData, assetType, dataSourceType);
// Extract the Data Import Execution ID
System.out.println(String.format("Data Import Execution ID: %s", dataImportExecution.getID().toString()));
}
{
}
{
}

See Also
DataImportStatus WSDL Information
DataImportStatus
Usage
Check the status of a Data Import.
Arguments
AssetType DataImportExecution
Response
DataImportExecutionStatus
Faults
Syntax
Service instance; AssetType assetType; DataImportExecution dataImportExecution;
DataImportExecutionStatus returnValue; returnValue = instance.DataImportStatus(assetType, dataImportExecution);

Sample Code - .NET
try
{
assetType.ID = 0;
assetType.Name = "Sample Data Import";
assetType.Type = "DataImport";
// Instantiate a new Data Import Execution object
EloquaDataService.DataImportExecution dataImportExecution = new EloquaDataService.DataImportExecution();
// Set the Data Import Execution ID (see InitializeDataImport)
dataImportExecution.ID = 1;
EloquaDataService.DataImportExecutionStatus status = service.DataImportStatus(assetType, dataImportExecution);
// Check the Data Import status
if (status == SampleCode.EloquaDataService.DataImportExecutionStatus.Complete)
{
Console.WriteLine("Data Import is Complete");
}
else
{
Console.WriteLine(String.Format("Status of the Data Import: {0}", status.ToString()));
}
}
{
}
{
}

try
{
assetType.setID(0);
assetType.setName(serviceFactory.createAssetTypeName("Sample Data Import"));
assetType.setType(serviceFactory.createAssetTypeType("DataImport"));
// Instantiate a new Data Import Execution object
EloquaDataService.DataImportExecution dataImportExecution = new EloquaDataService.DataImportExecution();
// Set the Data Import Execution ID (see InitializeDataImport)
dataImportExecution.setID(1);
EloquaDataService.DataImportExecutionStatus status = service.dataImportStatus(assetType, dataImportExecution);
// Check the Data Import status
if (status == EloquaDataService.DataImportExecutionStatus.COMPLETE)
{
System.out.println("Data Import is complete");
}
else
{
System.out.println(String.format("Status of the Data Import: %s", status.values().toString()));
}
}
{
}
{
}

See Also
InitializeDataImport WSDL Information
Errors
BatchSizeExceededFault
An operation tried to process more records than allowed by the maximum batch size. Consider using the Data Transfer service when working with large data sets.
DuplicateValue
A duplicate value is not permitted.
InvalidDataType
The data type is invalid.
ItemNotFound
The item was not found.
MaximumLengthExceeded
The maximum length was exceeded.
OperationTimeIntervalFault
The operation was requested too many times within the specified time interval.
QueryTooLargeFault
Query results are too large. Consider using the Data Transfer service when working with large data sets.
RequiredFieldNotSpecified
The operation requires a field that was not supplied.
UnauthorizedAction
The operation’s requestor was not authorized or does not have the appropriate permission.
UnexpectedDataException
The supplied data was not in the expected format.
UnexpectedException
An unexpected error occurred. This represents an internal error in Eloqua.

Eloqua web services api 1.2 user guide v1.0.1

More Related Content

What's hot (18)

Viewers also liked (6)

Similar to Eloqua web services api 1.2 user guide v1.0.1 (20)

Recently uploaded (20)

Eloqua web services api 1.2 user guide v1.0.1