Sending API requests

A basic request has several components not including authentication. An Oracle Eloqua API request follows the form:

[Verb] [baseURL]/API/[APIName]/[APINumber]/[endpoint]

Where...

  • baseURL is 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

In the sections below you will find articles explaining how to form a request and what to expect from responses.

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.
  • 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 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.

URL parameters

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.

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.

For more information about the endpoints beyond the reference material, such as tutorials and walkthroughs, see the links below.

Learn more about bulk endpoints.

Learn more about Application Endpoints.