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:
- 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.
- 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.
- 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.
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.
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:
<host> can be
secure.p03. To find your URL, see: Determining base URLs
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
limitis 1000, specifying an
offsetof 1000 will return records 1000 through 2000.
q: Specifies query criteria used to filter results. The
<term><operator><value>. For example:
orderBy: Specifies the name of the property to order the results by. The
DESC. For example,
Eloqua's bulk API supports most common HTML headers: in addition to the authentication headers for users of Basic Authentication, the
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
POST requests. The bulk API does not support XML. For
POST requests, you must specify either
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
DELETE requests, because these do not accept data inputs.
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:
The response would resemble:
The following requests the list of contact fields in JSON format:
The response resembles:
"name": "Email Address",
"name": "First Name",
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.
"name": "Docs Import Example",