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.
Pattern
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.
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 returnoffset: Specifies an offset that allows you to retrieve the next batch of records. For example, if yourlimitis 1000, specifying anoffsetof 1000 will return records 1000 through 2000.q: Specifies query criteria used to filter results. Theqformat is<term><operator><value>. For example:name='Email*''.orderBy: Specifies the name of the property to order the results by. TheorderByformat is<term>ASC|DESC. For example,orderBy=nameASC.
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.
Content-Type
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.
Accept
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:
name,internalName,dataType,defaultValue,hasReadOnlyConstraint,hasNotNullConstraint
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.
Request:
https://<host>.eloqua.com/API/Bulk/2.0/contact/import/123
Response:
{
"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"
}