Using import and export parameters

Import and export parameters enable you to control and describe your imports and exports with the Bulk API. This tutorial will walkthrough how to use the following parameters:

mapDataCards (Imports)
syncActions(Imports and Exports)
importPriorityUri (Imports)
updateRule (Imports)
areSystemTimestampsInUTC (Exports)
linkUsers (Imports)
updateRuleByField (Imports)

All of these parameters are optional. See Import Characteristics or Export Characteristics for a full list of available parameters.

mapDataCards

The mapDataCards parameter enables you to decide whether or not custom object records or event registrants will be mapped on import. If set to true, you'll need to specify the Eloqua entity field for mapping and the field that will be used for matching.

Here are the parameters you'll need to familiarize yourself with:

mapDataCards (boolean): Whether or not custom object records or event registrants will be mapped on import. By default, mapDataCards is false. If you set it to true, you must specify the fields for mapping.
mapDataCardsEntityField (string): Specifies which Eloqua entity field will be used for mapping.
mapDataCardsSourceField (string): Specifies the source field that will be used for matching.
mapDataCardsEntityType (string): Specifies the entity of the custom object record or event import. Allowed values are "Contact" or "Company".
mapDataCardsCaseSensitiveMatch (boolean): Whether to perform a case sensitive search when mapping custom object records or events to a contact or account.

Example

Let's create a new custom object import and map records to contacts using the contact field ContactIdExt:

HTTP Request

POST /api/bulk/2.0/customObjects/8/imports
Content-Type: application/json

Request Body

{
  "name": "Simple CDO Contact Import 2",
  "mapDataCards": "true",
  "mapDataCardsEntityField": "{{Contact.Field(ContactIDExt)}}",
  "mapDataCardsSourceField": "ContactIDExt",
  "mapDataCardsEntityType": "Contact",
  "mapDataCardsCaseSensitiveMatch": "false",
  "updateRule": "always",
  "dataRetentionDuration": "P7D",
  "fields": {
    "email": "{{CustomObject[8].Field[58]}}",
    "first": "{{CustomObject[8].Field[405]}}",
    "contactIDExt": "{{CustomObject[8].Field[406]}}"
  },
  "identifierFieldName": "contactIDExt"
}

"mapDataCardsEntityField": "{{Contact.Field(ContactIDExt)}}"
Because we want to map records to contacts using their contact ID, we are setting mapDataCardsEntityField to {{Contact.Field(ContactIDExt)}} because {{Contact.Field(ContactIDExt)}} is the internal Eloqua name for the field.
"mapDataCardsSourceField": "ContactIDExt"
The source field from the imported data that we will use for mapping is ContactIDExt, so we have set mapDataCardsSourceField to ContactIDExt.
"contactIDExt": "{{CustomObject[8].Field[406]}}"
Whichever field you use for mapping has to exist in both entities (in this case on a contact record and CDO record). Meaning we have to create a new custom object data field for the contactIDExt value.

Response

{
  "id": 836,
  "parentId": 8,
  "mapDataCards": true,
  "mapDataCardsCaseSensitiveMatch": false,
  "mapDataCardsEntityField": "{{Contact.Field(ContactIDExt)}}",
  "mapDataCardsSourceField": "ContactIDExt",
  "mapDataCardsEntityType": "Contact",
  "name": "Simple CDO Contact Import 2",
  "updateRule": "always",
  "fields": {
    "email": "{{CustomObject[8].Field[58]}}",
    "first": "{{CustomObject[8].Field[405]}}",
    "ContactIDExt": "{{CustomObject[8].Field[406]}}"
  },
  "identifierFieldName": "ContactIDExt",
  "isSyncTriggeredOnImport": false,
  "dataRetentionDuration": "P7D",
  "isUpdatingMultipleMatchedRecords": false,
  "uri": "/customObjects/8/imports/836",
  "createdBy": "API.User",
  "createdAt": "2016-02-01T21:43:03.7931253Z",
  "updatedBy": "API.User",
  "updatedAt": "2016-02-01T21:43:03.7931253Z"
}

Example

You may also want to include contact fields in the custom object import. We will use the mapDataCardsEntityField parameter and match on contact email address. When updating contacts, you should always match on email address, as Eloqua will try to create new contacts if the email address doesn't already exist.

Note: When using the Bulk API, entities related to core entities are available as long as the relationship resolves to a single entity and not many. For example, Account fields could be included in Contact exports and Contact fields could be included in Custom Object exports, as the relationship in these scenarios always resolves to a single entity. Custom Objects do not always resolve to a single entity, i.e. there could be more than one Custom Object record mapped to a Contact, so Custom Object fields cannot be included in Contact exports. Read more within the Eloqua Markup Language version 2 reference page under the Available entities section.

Let's create a new custom object import that includes contact fields:

HTTP Request

POST /api/bulk/2.0/customObjects/8/imports
Content-Type: application/json

Request Body

{
  "mapDataCards": true,
  "mapDataCardsCaseSensitiveMatch": false,
  "mapDataCardsEntityField": "{{Contact.Field(C_EmailAddress)}}",
  "mapDataCardsSourceField": "customObjectEmail",
  "mapDataCardsEntityType": "Contact",
  "name": "Custom Object Import with Contact Updates",
  "updateRule": "always",
  "fields": {
    "customObjectEmail": "{{CustomObject[8].Field[103]}}",
    "contactFirstName": "{{CustomObject[8].Contact.Field(C_FirstName)}}"
  },
  "identifierFieldName": "customObjectEmail",
  "isSyncTriggeredOnImport": true
}

syncActions

The syncActions parameter enables you to declare in an import or export definition that Eloqua should perform additional actions when you importing or exporting data. Using a sync action parameter generally involves specifying the action to perform and the destination for the entities.

See Sync actions parameters to see a full list of actions you can perform using this parameter.

Example

Create a contact import definition and use a sync action to add contacts to a contact list:

HTTP Request

POST /api/bulk/2.0/contacts/imports
Content-Type: application/json

Request Body

{
  "name": "Email Address Import",
  "fields": {
    "EmailAddress": "{{Contact.Field(C_EmailAddress)}}"
  },
  "identifierFieldName": "EmailAddress",
  "syncActions": [
    {
      "destination": "{{ContactList[31]}}",
      "action": "add"
    }
  ]
}

Response

{
    "name": "Email Address Import",
    "fields": {
        "EmailAddress": "{{Contact.Field(C_EmailAddress)}}"
    },
    "identifierFieldName": "EmailAddress",
    "syncActions": [
        {
            "destination": "{{ContactList[31]}}",
            "action": "add"
        }
    ],
    "isSyncTriggeredOnImport": false,
    "dataRetentionDuration": "P7D",
    "isUpdatingMultipleMatchedRecords": false,
    "uri": "/contacts/imports/3",
    "createdBy": "API.User",
    "createdAt": "2018-01-29T14:29:15.2227712Z",
    "updatedBy": "API.User",
    "updatedAt": "2018-01-29T14:29:15.2227712Z"
}

importPriorityUri

The importPriorityUri parameter is used to set the import to a different priority which overrides the default bulk API priority set in your Eloqua instance. You're able to discover your import priorities via this endpoint,

If you are not familiar with how Eloqua handles data import priorities, see Data import priority for more information.

Example

Create a new import and set the data import priority to #1.

HTTP request

POST /api/bulk/2.0/contacts/imports
Content-Type: application/json

Request body

{
   "name":"Email Address Import",
   "importPriorityUri":"/imports/priorities/100001",
   "fields":{
      "EmailAddress":"{{Contact.Field(C_EmailAddress)}}"
   },
  "identifierFieldName": "EmailAddress"
}

Response

{
  "name": "Email Address Import",
  "importPriorityUri": "/imports/priorities/100001",
  "fields": {
    "EmailAddress": "{{Contact.Field(C_EmailAddress)}}"
  },
  "identifierFieldName": "EmailAddress",
  "isSyncTriggeredOnImport": false,
  "dataRetentionDuration": "P7D",
  "isUpdatingMultipleMatchedRecords": false,
  "uri": "/contacts/imports/15",
  "createdBy": "API.User",
  "createdAt": "2018-01-24T15:29:02.5037857Z",
  "updatedBy": "API.User",
  "updatedAt": "2018-01-24T15:29:02.5037857Z"
}

updateRule

Import definitions include an updateRule parameter, which specifies how Eloqua should handle updating records when you import a new value for an existing field. For example, if contact Sally Jones's email address in Eloqua is sally.jones9@example.com, and you import a new email address for Sally Jones, the updateRule determines whether Eloqua should retain the existing email address or replace it with the new one. If you do not specify an updateRule, the rule type defaults to always.

The following rule types are available:

always: Always update.
ifNewIsNotNull: Update if the new value is not blank.
ifExistingIsNull: Update if the existing value is blank.
useFieldRule: Use the rule defined at the field level.

Example

Create a new contact import definition and set the update rule to always replace existing records with new values.

HTTP request

POST /api/bulk/2.0/contacts/imports
Content-Type: application/json

Request body

{
  "name": "Email Address Import",
  "fields": {
    "EmailAddress": "{{Contact.Field(C_EmailAddress)}}",
    "FirstName": "{{Contact.Field(C_FirstName)}}",
    "LastName": "{{Contact.Field(C_LastName)}}",
    "Company": "{{Contact.Field(C_Company)}}",
    "Address1": "{{Contact.Field(C_Address1)}}",
    "Address2": "{{Contact.Field(C_Address2)}}",
    "City": "{{Contact.Field(C_City)}}",
    "StateProvince": "{{Contact.Field(C_State_Prov)}}"
  },
  "identifierFieldName": "EmailAddress",
  "updateRule": "always"
}

Response

{
  "name": "Email Address Import",
  "updateRule": "always",
  "fields": {
    "EmailAddress": "{{Contact.Field(C_EmailAddress)}}",
    "FirstName": "{{Contact.Field(C_FirstName)}}",
    "LastName": "{{Contact.Field(C_LastName)}}",
    "Company": "{{Contact.Field(C_Company)}}",
    "Address1": "{{Contact.Field(C_Address1)}}",
    "Address2": "{{Contact.Field(C_Address2)}}",
    "City": "{{Contact.Field(C_City)}}",
    "StateProvince": "{{Contact.Field(C_State_Prov)}}"
  },
  "identifierFieldName": "EmailAddress",
  "isSyncTriggeredOnImport": false,
  "dataRetentionDuration": "P7D",
  "isUpdatingMultipleMatchedRecords": false,
  "uri": "/contacts/imports/6",
  "createdBy": "API.User",
  "createdAt": "2018-01-29T14:44:42.7717370Z",
  "updatedBy": "API.User",
  "updatedAt": "2018-01-29T14:44:42.7717370Z"
}

areSystemTimestampsInUTC

The boolean parameter areSystemTimestampsInUTC enables you to control whether system timestamps will be exported in coordinated universal time (UTC).

Example

With areSystemTimestampsInUTC set to true, export accounts that have been created after September 9, 2016 13:46:20.975 UTC:

HTTP request

POST /api/bulk/2.0/accounts/exports
Content-Type: application/json

Request body

{
  "name": "System Timestamps in UTC Export",
  "fields": {
    "companyName": "{{Account.Field(M_CompanyName)}}",
    "createdDate": "{{Account.Field(M_DateCreated)}}",
    "modifiedDate": "{{Account.Field(M_DateModified)}}"
  },
  "areSystemTimestampsInUTC": true,
  "filter": "'{{Account.Field(M_DateCreated)}}' > '2016-09-01 13:46:20.975'"
}

Response

{
  "name": "System Timestamps in UTC Export",
  "fields": {
    "companyName": "{{Account.Field(M_CompanyName)}}",
    "createdDate": "{{Account.Field(M_DateCreated)}}",
    "modifiedDate": "{{Account.Field(M_DateModified)}}"
  },
  "filter": "'{{Account.Field(M_DateCreated)}}' > '2016-09-01 13:46:20.975'",
  "dataRetentionDuration": "PT12H",
  "areSystemTimestampsInUTC": true,
  "uri": "/accounts/exports/92",
  "createdBy": "API.User",
  "createdAt": "2020-10-30T00:31:10.4176409Z",
  "updatedBy": "API.User",
  "updatedAt": "2020-10-30T00:31:10.4176409Z"
}

linkUsers

The linkUsers parameter is a boolean parameter that enables you to link users from a CRM to your Eloqua accounts during an account import.

If linkUsers is set to true one of the following CRM User ID fields is required in the Account import definition:

CRMOSCUserId
CRMSfdcUserId
CRMMSDUserId
CRMSODUserId

The statement formatting is:

{{Account.User.Field(<Field Name>)}}

Where <Field Name> is the CRM User ID field.

Example

Create an Account Import definition, and link users using the field "Oracle Sales Cloud User ID" (CRMOSCUserId):

HTTP request

POST /api/bulk/2.0/accounts/imports
Content-Type: application/json

Request body

{
  "name": "Import Accounts and link to Users",
  "fields": {
    "CompanyName": "{{Account.Field(M_CompanyName)}}",
    "UserCRMIdLink": "{{Account.User.Field(CRMOSCUserId)}}"
  },
  "identifierFieldName": "CompanyName"
  "linkUsers": "true"
}

Response

{
  "linkUsers": true,
  "name": "Import Accounts and link to Users",
  "fields": {
    "CompanyName": "{{Account.Field(M_CompanyName)}}",
    "UserCRMIdLink": "{{Account.User.Field(CRMOSCUserId)}}"
  },
  "identifierFieldName": "CompanyName",
  "isSyncTriggeredOnImport": false,
  "dataRetentionDuration": "P7D",
  "isUpdatingMultipleMatchedRecords": false,
  "uri": "/accounts/imports/41",
  "createdBy": "API.User",
  "createdAt": "2020-10-29T18:33:18.8585154Z",
  "updatedBy": "API.User",
  "updatedAt": "2020-10-29T18:33:18.8585154Z"
}

updateRuleByField

Import definitions include an updateRuleByField parameter, which specifies how Eloqua should handle updating records when you import a new value for an existing field by field. If you do not specify an updateRuleByField, or leave a field out of updateRuleByField, the rule type defaults to the rule set with updateRule. The following rule types are available:

always: Always update.
ifNewIsNotNull: Update if the new value is not blank.
ifExistingIsNull: Update if the existing value is blank.
useFieldRule: Use the rule defined at the field level.

Example

Create a new contact import definition and set the update rule by field, for some fields.

HTTP request

POST /api/bulk/2.0/accounts/imports
Content-Type: application/json

Request body

{
  "name": "updateRuleByField Import",
  "fields": {
    "EmailAddress": "{{Contact.Field(C_EmailAddress)}}",
    "FirstName": "{{Contact.Field(C_FirstName)}}",
    "LastName": "{{Contact.Field(C_LastName)}}",
    "Company": "{{Contact.Field(C_Company)}}",
    "Address1": "{{Contact.Field(C_Address1)}}",
    "Address2": "{{Contact.Field(C_Address2)}}",
    "City": "{{Contact.Field(C_City)}}",
    "StateProvince": "{{Contact.Field(C_State_Prov)}}"
  },
  "identifierFieldName": "EmailAddress",
  "updateRule": "always",
  "updateRuleByField": {
    "FirstName": "ifNewIsNotNull",
    "LastName": "useFieldRule",
    "Company": "ifExistingIsNull"
  }
}

Response

{
    "name": "updateRuleByField Import",
    "updateRule": "always",
    "fields": {
        "EmailAddress": "{{Contact.Field(C_EmailAddress)}}",
        "FirstName": "{{Contact.Field(C_FirstName)}}",
        "LastName": "{{Contact.Field(C_LastName)}}",
        "Company": "{{Contact.Field(C_Company)}}",
        "Address1": "{{Contact.Field(C_Address1)}}",
        "Address2": "{{Contact.Field(C_Address2)}}",
        "City": "{{Contact.Field(C_City)}}",
        "StateProvince": "{{Contact.Field(C_State_Prov)}}"
    },
    "updateRuleByField": {
        "FirstName": "ifNewIsNotNull",
        "LastName": "useFieldRule",
        "Company": "ifExistingIsNull"
    },
    "identifierFieldName": "EmailAddress",
    "isSyncTriggeredOnImport": false,
    "dataRetentionDuration": "P7D",
    "isUpdatingMultipleMatchedRecords": false,
    "uri": "/contacts/imports/854",
    "createdBy": "API.User",
    "createdAt": "2022-02-24T23:48:28.2330000Z",
    "updatedBy": "API.User",
    "updatedAt": "2022-02-24T23:48:28.2330000Z"
}

Using import and export parameters

mapDataCards

Example

Example

syncActions

Example

importPriorityUri

Example

updateRule

Example

areSystemTimestampsInUTC

Example

linkUsers

Example

updateRuleByField

Example

Learn more