Export data from Eloqua

The process for exporting data from Eloqua using the bulk API follows 3 basic steps:

  1. Create the export definition
  2. Synchronize the outgoing data into a temporary staging area
  3. Retrieve the data

Eloqua supports export definitions for Activities, Accounts, Contacts, Custom objects, Events, and Campaign responses.

In this tutorial:

Important: If you are working with large volumes of data, you should break your dataset into smaller segments using filters. Learn more about Bulk API limits.

To export data from Eloqua

  1. Create the export definition, which outlines your request's details. Once you create it, Eloqua will respond with a URI, which you will need in order to synchronize the data for export (step 2).

    Definition parameters

    NameRequired/OptionalDescription
    nameRequiredThe name of your export for reference
    fieldsRequiredThis is the most important parameter in your export definition. It defines which fields of the Eloqua record you are exporting will be mapped to the export output. A field parameter is made up of a name value and a field statement, for example: "ActivityId":"{{Activity.Id}}". The name value can be anything you want and doesn't need to match the Eloqua field name. The statement on the other hand needs to be valid Eloqua markup language and must match an existing field for the record being exported. You can retrieve detailed field information by calling the fields endpoint. Learn more about retrieving fields information.
    filterOptionalFilters allow you to select the exact data that you wish to export. For instance if you only wish to export contact records where the company field is of a certain value (such as Oracle employees) you can do so using a filter. Learn more about bulk API filtering.
    syncActionsOptionalSync Actions are parameters that you declare in an import or export definition that specify additional actions Eloqua should take when you import or export data. Learn more about sync actions.
    areSystemTimestampsInUTCOptional

    Enables you to control whether system timestamps will be exported in coordinated universal time (UTC). Learn more.

    The following export definition requests all Activity records where the activity type is FormSubmit. There are different endpoints depending on whether you're creating an export definition for Activities, Accounts, Contacts, Custom objects, Events, or Campaign responses.

    Request:

    POST /bulk/2.0/activities/exports

    Request body:

    {
   "name":"Example Activity Export",
   "fields":{
      "ActivityId":"{{Activity.Id}}",
      "AssetName":"{{Activity.Asset.Name}}",
      "ActivityType":"{{Activity.Type}}",
      "ActivityDate":"{{Activity.CreatedAt}}",
      "ContactId":"{{Activity.Contact.Id}}",
      "VisitorId":"{{Activity.Visitor.Id}}",
      "AssetType":"{{Activity.Asset.Type}}",
      "AssetId":"{{Activity.Asset.Id}}",
      "RawData":"{{Activity.Field(RawData)}}"
   },
   "filter":"'{{Activity.Type}}'='FormSubmit'"
}

    A successful response will include the export definition's name, fields and filter parameters, along with the new uri field, the name of the user who created and updated it, and timestamps for the creation and update.

    Response:

    {
    "name":"Example Activity Export",
    "fields":{
        "ActivityId":"{{Activity.Id}}",
        "AssetName":"{{Activity.Asset.Name}}",
        "ActivityType":"{{Activity.Type}}",
        "ActivityDate":"{{Activity.CreatedAt}}",
        "ContactId":"{{Activity.Contact.Id}}",
        "VisitorId":"{{Activity.Visitor.Id}}",
        "AssetType":"{{Activity.Asset.Type}}",
        "AssetId":"{{Activity.Asset.Id}}",
        "RawData":"{{Activity.Field(RawData)}}"
    },
    "filter":"'{{Activity.Type}}'='FormSubmit'",
    "dataRetentionDuration":"P7D",
    "uri":"/activities/exports/26331",
    "createdBy":"API.User",
    "createdAt":"2015-07-16T19:14:13.5598178Z",
    "updatedBy":"API.User",
    "updatedAt":"2015-07-16T19:14:13.5598178Z"
}

    Save the uri field value for the next step, in this case: /activities/exports/26331.

  2. Synchronize the data. Once you have your export definition's uri, you can use it to synchronize the requested data. This is done by sending the export definition's uri to the /syncs endpoint. Continuing the above example, the request would be: 
    POST /bulk/2.0/syncs

    Request body:

    {
   "syncedInstanceUri" : "/activities/exports/26331"
}

    The response will include a status parameter, creation metadata, and the sync uri:

    {
    "syncedInstanceUri":"/activities/exports/26331",
    "status":"pending",
    "createdAt":"2015-07-16T19:25:14.0808068Z",
    "createdBy":"API.User",
    "uri":"/syncs/52524"
}

    The sync status is pending. As the sync progresses, the status will change. You'll need to check the status of the sync by sending a GET request to the sync's uri using the Retrieve a sync endpoint.

    Tip: To avoid polling to check the sync's status, the syncs endpoint has an optional callbackUrl parameter available. When a sync completes, Eloqua will make a call to the URL specified in this parameter. Learn more about the sync endpoint.

    Send a GET request to retrieve the sync using the sync's uri . Continuing the example above:

    GET /bulk/2.0/syncs/52524

    When the sync is complete there will be a 200 OK response that resembles the following:

    {
    "syncedInstanceUri":"/activities/exports/26331",
    "syncStartedAt":"2015-07-16T19:25:14.3900000Z",
    "syncEndedAt":"2015-07-16T19:25:19.9370000Z",
    "status":"success",
    "createdAt":"2015-07-16T19:25:13.6930000Z",
    "createdBy":"API.User",
    "uri":"/syncs/52524"
}
  3. Retrieve the data you have synchronized using the sync URI's data endpoint.

    Continuing the example, the request would be:

    GET /bulk/2.0/syncs/52524/data

    The response will include the requested records within the items property:

    {
    "Count": 1,
    "hasMore": false,
    "limit": 1000,
    "offset": 1,
    "totalResults": 1,
    "items": [
        {
            "ActivityId": "999",
            "AssetName": "Forms-BulkActivity",
            "ActivityType": "FormSubmit",
            "ActivityDate": "2014-01-29 13:45:31",
            "EmailAddress": "allison@example.com",
            "ContactId": "123",
            "VisitorId": "1",
            "AssetType": "Form",
            "AssetId": "1",
        }
    ]
}

    Note: If you do not specify a limit when you send your GET request, the limit defaults to 1000. You can specify any limit up to 50000, though requesting larger volumes may create performance issues.

    If there were more than 1000 matching items, hasMore would be true and you would be able to request the next batch of items using an appropriate offset. For example, if there were 1500 items, the following call would request items 1000 through 1500:
    GET /bulk/2.0/syncs/52524/data?offset=1000

    For more information on how to use these query parameters, see Retrieving large volumes of data.

    See the syncs data endpoint documentation for full list of URL parameters.

    Data Export Timeouts

    • Contacts, Activities, Custom Objects, and Events: 6 hours
    • Accounts and Campaign Responses: 1 hour