API call format

All bulk API calls use the same general call pattern: whether you are importing or exporting data, the structure of your call will be consistent.


Importing and exporting data with the bulk API follows a three-step pattern:

  1. Define the import or export. The definition describes how Eloqua's fields map to your own. For example, your email field might map to Eloqua's Contact.Field(C_EmailAddress). You can also give the definition a name, so that you can reuse it later, specify how to filter the data, and define any additional actions you want to perform. The import or export definition tells Eloqua what kind of operation to prepare to perform.
  2. Move data into the staging area. For imports, this means POSTing your data to the staging area; for exports, this means telling Eloqua to move its data into the staging area. The staging area is a middle ground that allows read and write operations to occur asynchronously from the HTTP requests you send.
  3. Move the data to its final destination. For imports, this means telling Eloqua to sync the data from the staging area into its database; for exports, this involves retrieving the data from the staging area.

This design allows for fast client requests, while longer actions are performed asynchronously. By not interacting with the Eloqua database during the HTTP request, you gain a consistent expectation of how long I/O operations will take. The asynchronous pattern also enables scalability: were I/O operations and merges performed inline, database locks would impact the performance of your Eloqua instance.

The staging area system allows data to be written to disk, and then processed in the background without affecting performance.

Basic structure

Familiarizing yourself with the common URI parameters, required HTTP headers, and JSON patterns will give you a strong foundation from which to start using the bulk API.

Call URL

The URL you need to call to access Eloqua’s Bulk API depends on which “pod” your Eloqua instance is hosted on. The base url is: https://<host>.eloqua.com/api/bulk/2.0, where <host> can be secure, www02.secure, or secure.p03. To find your URL, see: Determining base URLs .

URL parameters

The bulk API's HTTP GET endpoints support a variety of URL parameters that you can use to control what data you retrieve.

  • limit: Specifies the maximum number of records to return
  • offset: Specifies an offset that allows you to retrieve the next batch of records. For example, if your limit is 1000, specifying an offset of 1000 will return records 1000 through 2000.
  • q: Specifies query criteria used to filter results. The q format is <term><operator><value>. For example: name='Email*''.
  • orderBy: Specifies the name of the property to order the results by. The orderBy format is <term> ASC | DESC. For example, orderBy=name ASC.

HTML headers

Eloqua's bulk API supports most common HTML headers: in addition to the authentication headers for users of Basic Authentication, the Content-Type and Accept headers specify data formats for the data you import into Eloqua and the bulk API's response data.


The bulk API supports both JSON and CSV file formats as data sources for PUT and POST requests. The bulk API does not support XML. For PUT and POST requests, you must specify either application/json or text/csv in the Content-Type header: if you do not include the Content-Type header an error will occur. The Content-Type header is not required for GET and DELETE requests, because these do not accept data inputs.


The Accept parameter specifies what file formats you, the client, are willing to accept from the server: either JSON or CSV. Use of the accept header is optional: if you do not specify a parameter for Accept, the response will default to JSON.

The following call requests the list of Contact fields in CSV format:

GET https://<host>.eloqua.com/api/bulk/2.0/contacts/fields
Accept: text/csv

The response would resemble:

Email Address,C_EmailAddress,emailAddress,,False,False
First Name,C_FirstName,string,,False,False

The following requests the list of contact fields in JSON format:

GET https://<host>.eloqua.com/api/bulk/2.0/contacts/fields
Accept: application/json

The response resembles:

"count": 82,
"hasMore": false,
"items": [
"createdAt": "1900-01-01T05:00:00.0000000Z",
"dataType": "emailAddress",
"hasNotNullConstraint": false,
"hasReadOnlyConstraint": false,
"hasUniquenessConstraint": true,
"internalName": "C_EmailAddress",
"name": "Email Address",
"statement": "{{Contact.Field(C_EmailAddress)}}",
"updatedAt": "1900-01-01T05:00:00.0000000Z",
"uri": "/contacts/fields/100001"
"createdAt": "1900-01-01T05:00:00.0000000Z",
"dataType": "string",
"hasNotNullConstraint": false,
"hasReadOnlyConstraint": false,
"hasUniquenessConstraint": false,
"internalName": "C_FirstName",
"name": "First Name",
"statement": "{{Contact.Field(C_FirstName)}}",
"updatedAt": "2013-03-26T21:32:13.2530000Z",
"updatedBy": "Docs.Example",
"uri": "/contacts/fields/100002"

Data Encoding

When uploading data, Eloqua expects data to be encoded with UTF-8.

Example call and response

You can create bulk API requests using whatever language you wish. The examples and tutorials in this guide show the basic request that you need to send to perform your request, ignoring language-specific code examples.




"createdAt": "2014-05-13T18:25:32.0270000Z",
"createdBy": "Docs.Example",
"fields": {
"C_EmailAddress": "{{Contact.Field(C_EmailAddress)}}",
"C_FirstName": "{{Contact.Field(C_FirstName)}}",
"C_LastName": "{{Contact.Field(C_LastName)}}"
"identifierFieldName": "C_EmailAddress",
"isSyncTriggeredOnImport": false,
"isUpdatingMultipleMatchedRecords": false,
"name": "Docs Import Example",
"syncActions": [],
"updatedAt": "2014-05-13T18:25:32.0270000Z",
"updatedBy": "Docs.Example",
"uri": "/contacts/imports/1183"

Learn more

Oracle Eloqua Bulk API