Bulk API frequently asked questions

General

What trims/versions of Eloqua is the bulk API available?

The bulk API is available on ALL trims and ALL versions of the API (E9 and E10, and Express, Team and Enterprise)

I am having trouble visualizing the Bulk API pattern? Are there any visual diagrams?

Asynchronous Flow

Importing Data

A diagram illustrating the import workflow of the Bulk API

Exporting Data

A diagram illustrating the export flow in the Bulk API

Is the API rate limited?

Every Eloqua instance has the following soft limits by Bulk API sync type:

Bulk API Sync Type Limit
Export 2000 per hour
Import 2000 per hour
Sync Action 4000 per hour

Here are the Bulk API limits:

  • The amount of data allowed on our servers in the staging area

    • The amount is based on the # of contacts allowed for the client x 50 in KB; So, for a client with 10 M contacts, this would result in 500 GB storage area for that client

  • Import Limits

    • Definition limit: An import definition can include a maximum of 100 fields

    • Request limit: There is a hard limit of 32 MB per request when posting data to an import sync's staging area

    • Staging limit: It is recommended to sync an import whenever approximately 250 MB of data has been posted to its staging area

  • Export Limits

    • Definition limits: An export definition can include a maximum of 250 fields

    • Request limit: There is a limit of 50,000 records per request while retrieving data from an export

    • Staging limit: When exporting activities there is a limit of 5 million records per sync.

Read more about limits.

Does the bulk API provide the ability to export contact data of any given set of fields based on some filter or other requirement?

Yes; an export is limited to 250 fields at once, but any of the contact fields are available at export as are the linked account fields. In addition, Contact attributes (subscription and bounceback status) are available.

For filtering, data can be exported from a contact list, filter or segment, or based on un/subscription to an email group, a cloud connector status or comparison of a single field on the contact. See Filtering for more information.

How do you retrieve all contacts that are in a contact list?

Export contacts based on their presence in the contact List with ID 123:

{
  "name": "List 123 Contacts Export",
  "fields": {
    "ID": "Contact.Id",
    "FirstName": "Contact.Field(C_FirstName)",
    "LastName": "Contact.Field(C_LastName)",
    "EmailAddress": "Contact.Field(C_EmailAddress)"
  },
  "filter": "EXISTS('ContactList[123]')"
}

See Filtering for more information on filtering.

Can you import a bunch of contacts with an arbitrary set of fields?

Yes, imports are also defined with any set of contact fields / attributes as are exports.

Can you import into a (contact) group/list?

Yes; similar to export filtering, except that you specify additions to a contact list by using a Sync Action, with the action = "add" and the destinationUri as the contact list's uri (ie "/contact/list/123"). See for Sync actions more information.

Can you import into a canvas?

You can create a Feeder Service to enable importing directly into a canvas.

Another option for importing contacts into a canvas is using a Bulk API sync action to add to list. The contact list could be used in a segment that gets re-evaluated which then would add them to a canvas.

Can you unsubscribe contacts from all future mailings (when importing)?

There are two options here:

Set the contact's global subscription status to unsubscribed. You interact with this almost like any other field (ie as a column in the import).

On import, use a sync action to unsubscribe from a particular email group.

What is the maximum number of fields that can be included in an export?

250

Note: When specifying fields for an app or service instance, you can specify a maximum amount of 249 fields because AppCloud developer reserves the contact ID field, which is required to update the status of records and move them to subsequent steps or pass cloud content.

I am coming close to the Bulk API syncs soft limit, or am already over this limit for one or more sync types. Am I going to get shut down? What's the impact of going over?

We want to encourage app/Bulk API usage, as long as app/Bulk API usage is not generating abusive API behavior. We advise not getting too caught up with the soft limit for Bulk API syncs, unless going over significantly, and/or observing performance issues related to the Bulk API load.

If you are going over this limit for one or more sync types, the chances of performance issues will increase with volume (meaning the higher you exceed the limit, the higher probability of experiencing performance issues). It's strongly recommended to stay as close to the soft limits as possible, to reduce the chance of performance issues. The main impact you'll see as the sync volume increases - is increased sync processing time with increased probability of performance issues. Performance issues are more likely to occur when there is a large Bulk API sync volume with other Eloqua activities (such as Lead Scoring, Form Processing, Segment Execution, and so on) occurring concurrently and/or also in large volumes. The lower the Bulk API sync volume, the smaller probability of performance issues when these other activities are occurring.

I am exporting all of my activities using the Bulk API. When I accumulate activities exported via the Bulk API, metrics are not matching what I see an Insight. Why wouldn't they match?

The are two primary reasons they don't match:

  1. Any data pulled from APIs does not include activity from deleted Contacts. Insight includes activity from deleted Contacts.

  2. Label-based Access Control (LBAC), if it's being used. The APIs respect LBAC, so sometimes the user placing the API request doesn't have access to view Contacts, or the User doesn't have access to view Contacts in Insight. Additionally, non contact related reports in Insight are not limited to the contacts that a user can access. For example, a campaign report will show data related to all campaign members.

Are there any best practices or resources for exporting all activities via the Bulk API?

Exporting All Eloqua Activities Using the Bulk API: Flowchart, Best Practices, and Resources

Is it possible the Bulk API would export duplicate records?

Yes, if you use UpdatedAt in the definition's filter the same record may be returned more than once if a record is updated during the export. This applies to all Bulk API exports that allow UpdatedAt in the filter.

Learn more

Oracle Eloqua Bulk API