Import data into Eloqua

To import data into Eloqua using the bulk API:

  1. Create the import definition.
  2. Upload the incoming data into a temporary staging area.
  3. Synchronize the data from the staging area into Eloqua.

Eloqua supports import definitions for activities, accounts, contacts, custom objects, and events.

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 import data into Eloqua

  1. Create the import definition.

    The import definition outlines your request's details. Once you create an import definition, Eloqua will respond with a uri which you will need in order to upload data into Eloqua (step 2).

    Definition parameters

    Name Required/Optional Description
    nameRequiredThe name of your import for reference
    fieldsRequiredThis is the most important parameter in your import definition. It defines which fields your imported data will be mapped to for the given Eloqua record type. 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.
    identifierFieldNameRequiredThis parameter is used to check the imported data against existing records within Eloqua. It should match one of the field names as defined in the above fields parameter. Choose a field that is likely to be unique to avoid updating the wrong record. Do not use a large text field as the identifierFieldName as this can produce errors.
    isSyncTriggeredOnImportOptional A Boolean parameter specifying whether the sync is triggered automatically upon import. If set to true, the Bulk API automatically syncs your data into Eloqua when you upload it to the staging area. If set to false, you must manually create the sync operation that merges your data into Eloqua. Manually syncing the data provides more control over the timing of the syncs, and allows you to break large sync operations into smaller batches. This can mitigate performance issues in your Eloqua instance. By default, isSyncTriggeredOnImport is set to false.
    dataRetentionDurationOptional The length of time that unsync’d data from this import should remain in the staging area. Bulk API 2.0 uses the ISO-8601 standard for specifying all durations. Valid values are anything from PT1H (1 hour) to P14D (2 weeks). This setting will default to P7D (7 days) if not explicitly set during definition creation.
    syncActionsOptional Sync 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.
    isUpdatingMultipleMatchedRecords Optional Whether or not imported data will be mapped to multiple existing records. Learn more.
    importPriorityUri Optional Must reference an existing /imports/priorities/{id}.

    The following import definition will map incoming data to Eloqua contact record fields, specifically firstName, lastName, and emailAddress. There are different endpoints depending on whether you're creating an import definition for Activities, Accounts, Contacts, Custom objects, or Events.

    Note: Creating an import definition is required if you are updating fields for the Eloqua record type. If you are not updating fields, the sync action definition endpoints can be used to specify up to 10 actions Eloqua should take without importing data. Using the sync action definition endpoints is always recommended if no updates are required, because it is a quicker operation than importing data. There are different endpoints for accounts, contacts, and custom objects. For a full list of available actions, see Sync actions.

    Request:

    POST /bulk/2.0/contacts/imports/

    Request body:

    {
    "name": "Docs Import Example",
    "fields": {
    "firstName": "{{Contact.Field(C_FirstName)}}",
    "lastName": "{{Contact.Field(C_LastName)}}",
    "emailAddress": "{{Contact.Field(C_EmailAddress)}}"
    },
    "identifierFieldName": "emailAddress",
    "isSyncTriggeredOnImport" : "false"
    }

    A successful response will include the import definition's name, fields, identifierFieldName, isSyncTriggeredOnImport, isUpdatingMultipleMatchedRecords, 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": "Docs Import Example",
    "fields": {
    "firstName": "{{Contact.Field(C_FirstName)}}",
    "lastName": "{{Contact.Field(C_LastName)}}",
    "emailAddress": "{{Contact.Field(C_EmailAddress)}}"
    },
    "identifierFieldName": "emailAddress",
    "isSyncTriggeredOnImport": false,
    "isUpdatingMultipleMatchedRecords": false,
    "uri": "/contacts/imports/1182",
    "createdBy": "Docs.Example",
    "createdAt": "2014-05-13T14:13:30.0402961Z",
    "updatedBy": "Docs.Example",
    "updatedAt": "2014-05-13T14:13:30.0402961Z"
    }

    You will use the returned uri parameter to upload data into Eloqua.

  2. Upload the data: Once you have your import definition's uri, you can use it to upload the incoming data.

    Continuing the above example, the request would be:

    POST /bulk/2.0/contacts/imports/1182/data

    Request body:

    [
    {
    "firstName": "Juan",
    "lastName": "Garcia",
    "emailAddress": "juan@example.com"
    },
    {
    "firstName": "Tatiana",
    "lastName": "Smirnov",
    "emailAddress": "tatiana@example.com"
    }
    ]

    The response, if successful is an HTTP 204 No Content message. The data is now in the staging area, ready to be synced into Eloqua.

    Note: There is a hard limit of 32 MB per request when posting data to an import sync's staging area. Requests larger than 32 MB will fail by returning a 404 Not Found response. To import more than 32 MB of data, you can make multiple posts of 32 MB (or less) to the import definition before syncing. It is recommended to sync an import whenever approximately 250 MB of data has been posted to its staging area.

  3. Synchronize the data: You can synchronize the data from the staging area into your Eloqua database.

    Note: If isSyncTriggeredOnImport was set to true, the sync occurs automatically and you can skip this step. If isSyncTriggeredOnImport is set to false, you must manually create the sync. If uploading more than 32 MB of data within a sync, isSyncTriggeredOnImport needs to be set to false to allow multiple requests for posting data.

    Continuing the above example, the request would be:

    POST /bulk/2.0/syncs

    Request body:

    {
    "syncedInstanceUri": "/contacts/imports/1182"
    }

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

    {
    "syncedInstanceUri": "/contacts/imports/1182",
    "status": "pending",
    "createdAt": "2014-05-13T17:58:34.0176959Z",
    "createdBy": "Docs.Example",
    "uri": "/syncs/1208"
    }

    The sync status is pending. As the sync progresses, the status message will change.

    Checking the status of the sync

    To check the status of the sync, send a GET request to the sync's uri. In this example:

    GET /bulk/2.0/syncs/1208

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

    {
    "syncedInstanceUri": "/contacts/imports/1182",
    "syncStartedAt": "2014-05-13T17:58:34.2770000Z",
    "status": "success",
    "createdAt": "2014-05-13T17:58:33.8130000Z",
    "createdBy": "Docs.Example",
    "uri": "/syncs/1208"
    }

    In order to avoid polling to check the sync's status, the syncs endpoint has an optional callbackUrl parameter available. Learn more about the sync endpoint.

Related

Fields