Import data into Eloqua

To import data into Eloqua using the bulk API:

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

Eloqua supports import definitions for activities, accounts, contacts, custom objects, and events. Email addresses are not included in this list of import definitions because they can only be used with sync actions.

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

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
`name`	Required	The name of your import for reference
`fields`	Required	This 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. Note: Lead scoring fields are read only and can only be used in Contact Exports.
`identifierFieldName`	Required	This 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.
`isSyncTriggeredOnImport`	Optional	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`.
`dataRetentionDuration`	Optional	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.
`syncActions`	Optional	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}.
`linkUsers`	Optional	Enables you to link users from a CRM to your Eloqua accounts during an account import. Learn more.
`updateRuleByField`	Optional	Specifies how Eloqua should handle updating records when you import a new value for an existing field by field. Learn more.

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.

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

Note: When uploading data, Eloqua expects data to be encoded with UTF-8.

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.
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"
}
```
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.

Learn more

Fields

Bulk API Best Practices

Import data into Eloqua

To import data into Eloqua

Definition parameters

Checking the status of the sync

Learn more