What is an Application Programming Interface (API)?
Simply put, an API allows software to communicate with other, external software. Programmers can write their own code through the API, which extends the functionality of the software. For web applications or services, like Eloqua, API operations are usually written using the Simple Object Access Protocol (SOAP) or Representational State Transfer (REST) services.
Why use API?
API can be used to integrate with external applications, build applications (see examples at appcloud.eloqua.com), solve complex use cases, and perform specific, repeatable tasks or functions.
The Three Eloqua APIs
There is some overlap between the three APIs and what they can be used for. For example, any one of these can be used to create or update contacts, accounts or data cards. REST and SOAP can work with assets as well, but Bulk cannot. See a list of supported operations for each API.
SOAP
SOAP uses a basic XML message framework, which you can build more abstract layers on top of. The SOAP handler on the Eloqua web server communicates with your instance of another web service, such as a CRM system, through a Hypertext Transfer Protocol (HTTP) or through an encrypted HTTP Secure (HTTPS) protocol, which are the same protocols used to exchange information through a standard Internet browser.
To help write operations for SOAP, programmers use a set of predefined XML parameters known as Web Services Description Language (WSDL), pronounced wiz-del or spelled out as W-S-D-L. WSDL is a set of specifications that can be reused.
In the SOAP API version 1.2, it’s easy to add to your project using WSDL. Because it’s a standardized specification, it can be processed by many middleware applications.
There are several WSDLs available, depending on what you want to do through the API. For more information, see the API Web Services Overview.
- https://secure.eloqua.com/API/1.2/Service.svc?wsdl
- https://secure.eloqua.com/API/1.2/DataTransferService.svc?wsdl
- https://secure.eloqua.com/API/1.2/EmailService.svc?wsdl
- https://secure.eloqua.com/API/1.2/CampaignService.svc?wsdl
Note: To access these links, the first step would be Using the Eloqua API - Determining Endpoint URLs. Furthermore, the static and live docs are provided as is and are not supported.
REST
REST is a web service that does not transfer messages using standardized parameters (like SOAP). Instead, REST uses operations that are defined by a Uniform Resource Identifier (URI) transferred through HTTP. You can use REST to retrieve lists of entities or assets, but it is not designed for large or bulk updates.
When using REST, it is important to be aware of the Eloqua Product Thresholds. We recommend a limit of one call per second for optimal performance. REST 1.0 is contractually stable and will not change. REST 2.0 is what Eloqua uses and may change over time (2.0 is not supported).
View the static code for the REST API 1.0.
- http://secure.eloqua.com/api/docs/Static/Rest/1.0/doc.htm
- http://secure.eloqua.com/api/docs/Static/Rest/1.0/index.htm
View the Live Docs. You will need to update the link depending on your POD’s subdomain, and you need to access the link in the same browser window that you are signed in to Eloqua on.
Bulk
Bulk API is a web service that is based on REST API. It is designed to import and export large volumes of data, such as contacts, custom objects, activities, and cloud connectors. It is designed only to add or update records, and not for other purposes such as deleting records or marking contacts as unsubscribed.
There is only one version for now, 1.0. The threshold for Bulk API is 2000 POST or PUT requests per day.
Guide on how to perform data imports and exports using the Bulk API.
View the static code for the Bulk API.
View the Live Docs. You will need to update the link depending on your POD’s subdomain, and you need to access the link in the same browser window that you are signed in to Eloqua on.
Getting Started
To perform API operations, you will need an Eloqua user with API permissions. Make sure you have an Eloqua user with access to the API Users security group. If you want to access assets through the API operations, you need to give the user access to additional groups, such as Advanced Users - Marketing.
Next, check out these resources on Topliners to learn more about what you can do with API and how to code it.
- Code It
- Building On The Eloqua Platform - A Resource Guide
- Eloqua API Chart - Supported Operations
- Eloqua API - Which one do I use?
You can also try these tools. They are a good place to start when you want to develop and test code:
If you need help with API, we recommend posting on Code It, as your use case may have been discussed before. The Product Support team does not troubleshoot custom code; however, they can provide guidance on supported operations and confirm any technical issues with the API itself. Before you submit a case, see what information Eloqua Support needs for API cases.