Getting Started with Bulk
While the Bulk API is designed for ease of use, there are things to bear in mind when determining how you will interact with the Bulk API.
Note:
Refer to the Eloqua Developer Help Center for more in-depth information about the Bulk API.Requirements
The Bulk API is designed to let developers start developing with minimal setup or configuration effort. At a minimum, you need an Eloqua instance and an account on that instance. In order to be able to interact with your Eloqua data, your account needs adequate permissions to access contact fields, secondary assets, and so on.
Some Eloqua instances enable contact-level security, which restricts access to data based on different user roles. Users might only have access to contacts located in their geographical region, for instance. Because these permissions affect what data the user can access, it is important that the Eloqua user accessing the API has the appropriate permissions.
Considerations
Use Case
The Bulk API does not constrain how you interact with it, but your use case should determine how you develop your integration.
For example, if you are importing data into Eloqua, you should consider resiliency: if an item fails to import, can you send it again in 15 minutes, or do you need to deal with the failure immediately? Your use case will determine what measures you need to put into place to deal with this.
Similarly, if you are exporting data from Eloqua, how large a data set are you working with? Larger exports will be time consuming, so you can break the export up into smaller chunks using a filter. Be aware of the data volumes you expect to deal with and create your export definitions accordingly.
The Troubleshooting section discusses ways you can monitor your imports and exports and leverage this data to improve your integration. The Bulk API Limits documentation can also help guide you when designing your interaction with the Bulk API.
Authentication and Security
Access to the Oracle Eloqua Bulk API requires adequate permissions based on security group. Oracle Eloqua utilizes SSL/TLS with support for 128-bit and 256-bit ciphers to securely transmit traffic in all API calls. The encryption level depends on the libraries being used by your app.
For authentication, Eloqua's Bulk API supports HTTP Basic Authentication as well as OAuth 2.0.
OAuth is the preferred method of authenticating. OAuth allows Bulk API-powered applications to access resources on behalf of a resource owner without needing the resource owner's credentials.
The Bulk API supports 2-legged OAuth for second party apps, and 3-legged OAuth for apps in the AppCloud.
In cases where implementing OAuth is not feasible, you can use HTTP Basic Authentication. This approach requires that you obtain the user's credentials, which is not ideal. For example, if a user changes their password, you will need to obtain the new password. If feasible, use OAuth over basic authentication.
The Authenticate Using OAuth and Authenticate using HTTP Basic Authentication tutorials provide step-by-step instructions for authenticating to Eloqua using each method.
Accessible Elements
The Bulk API is gives you access to contacts, accounts, custom data objects, email groups, external activities, events, campaign responses, and opportunities. See: Introduction to Eloqua Elements for a full description of each element.
API Call Format
Interactions with the Bulk API follow a consistent pattern: you create a record definition that tells Eloqua what data you are importing or exporting, move that data into a staging area, and either retrieve the data, in the case of an export, or push that data into Eloqua, in the case of an import.
The API Call Format topic explores this pattern in detail, touching on the rationale behind the three-step workflow. It also discusses data formatting requirements, header requirements, and so on.
You should familiarize yourself with the API call format before starting to work with the Bulk API.