Sending API requests
A basic application and Bulk API request has several components not including authentication. An Oracle Eloqua application and Bulk API request follows the form:
[Verb] [baseURL]/API/[APIName]/[APINumber]/[endpoint]
Where...
baseURLis the location of your data center. See Determining base URLs for more information.[APIName]is the name of the API, such as "rest" or "bulk"[APINumber]is the version of the API, such as "1.0" or 2.0"
Therefore an example of a complete request would be as follows:
GET https//secure.<pod>.eloqua.com/API/rest/1.0/assets/emails
The reporting API requests follow the form:
GET [base URL]/API/odata/[subjectArea]/[APIVersionIdentifier]/[endpoint]
Where [subjectArea] is the subject area of the endpoint, such as "campaignAnalysis", and [APIVersionIdentifier] is the version of the API, such as "1.0".
Here is an example of a complete reporting API request:
GET https://secure.p03.eloqua.com/api/odata/campaignAnalysis/1.0/campaign
Learn more about the reporting API.
Learn more by watching the video
Determining Base URLs
Before you can send a request, you must determine the Eloqua data center for which your instance is located. Your data center is a component of your API request, if continuing our example above, the data center is the <pod> component of your request. Eloqua supports multiple data centers, and the https://login.eloqua.com/id endpoint allows you to interface with Eloqua regardless of where the Eloqua install is located. It is important to validate your base URL before making any API calls. If you don't validate, your API calls may not work.
HTTP verbs
Eloqua's API services support four different methods or "verbs": POST, GET, PUT and DELETE. In terms of database functions, these HTTP verbs correspond to the basic operations of "CRUD": create, read, update and delete.
- GET is used to retrieve a representation or API entity from a resource. Can be used to retrieve one or more entities. The reporting API only supports GET requests.
- POST is used to create a new resource.
- PUT is used to update a resource.
- DELETE is used to delete a resource.
HTTP request headers
Multiple request headers may be required for API requests to Eloqua's APIs, depending on the endpoint. The documentation for that endpoint will explain which headers are required. Generally, the request headers for most Eloqua endpoints are similar.
Request depth
Eloqua application and Bulk APIs can retrieve entities at three different levels of depth: minimal, partial, and complete. In general, requests at minimal depth will perform best, as they scan the least amount of data. For most application API endpoint properties, if a property in the root of the response does not have a value, that property will not be returned.
Note: The reporting API does not support request depth. Learn more about reporting API query options.
URL parameters
Application and Bulk request endpoints may also contain one or more URL parameters. Parameters are used to customize requests so as to more easily manipulate information in the database.
HTTP status codes
In most cases Eloqua's APIs will respond to requests with the standard HTTP status code definitions. If the API fails to validate a request, it will respond with a validation error message (JSON or XML) describing the issue.
Bulk API status codes
In addition to the standard HTTP status codes, Eloqua includes specific status codes to help inform you when performing operations with the their APIs. Each status code has a number, as well as a human-readable message.
Learn about bulk API status codes
Validation errors
If the API fails to validate a request, it will respond with a 400 validation error message (JSON or XML) describing the issue.
Endpoints
Endpoints allow access to Oracle Eloqua resources and operations. Each resource/operation is associated with a specific URL. Endpoints have can be accessed and manipulated through HTTP verbs, but not all verbs are valid for all endpoints.
Note: An endpoint is sometimes referred to as a "URI" or uniform resource identifier.
For example, performing a GET request on the REST 1.0 "assets/emails" endpoint will return a list of all the emails in your instance's database. However, you cannot perform a POST request on this endpoint.
See the API reference documentation
For more information about the endpoints beyond the reference material, such as tutorials and walkthroughs, see the links below.