Importing account data

This tutorial will go into detail on how to import account data into Eloqua, and provide example use cases for doing so. The Import data into Eloqua tutorial provides a general example of how to import all data types such as activity data, account data, contact data, custom object data, and event data into Eloqua. Refer to Import data into Eloqua for general rules for importing data.

Use case: Importing accounts and linking users to accounts

The following example demonstrates how to import accounts and link users to accounts.

To import accounts and link users to accounts:

  1. Create the account import definition.

    Request:

    POST /bulk/2.0/accounts/imports

    Request body:

    In the request body we will set linkUsers to true, to indicate we will be linking users to accounts.

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

    A successful response will include the import definition's name, fields, identifierFieldName, isSyncTriggeredOnImport, isUpdatingMultipleMatchedRecords, linkUsers, along with the new uri field, the name of the user who created and updated it, and timestamps for the creation and update.

    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/43",
      "createdBy": "API.User",
      "createdAt": "2020-11-09T17:35:22.6488629Z",
      "updatedBy": "API.User",
      "updatedAt": "2020-11-09T17:35:22.6488629Z"
    }

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

  2. Upload the account data into a temporary staging area, using the uri from step 1.

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

    Request:

    POST /bulk/2.0/accounts/imports/43/data

    Request body:

    In the request body we can specify multiple User IDs to upload to the account, separated by commas. Note this applies only when using the UserCRMIdLink field.

    [
      {
        "CompanyName": "Eloqua",
        "UserCRMIdLink": "754a1a4baadb4ace991ee,754a1a4baadb4ace991ea"
      }
    ]
    

    Response:

    204 No Content

    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.

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

    Continuing the above example, the request would be:

    POST /bulk/2.0/syncs

    Request body:

    {
      "syncedInstanceUri": "/accounts/imports/43"
    }

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

    {
      "syncedInstanceUri": "/accounts/imports/43",
      "status": "pending",
      "createdAt": "2020-11-09T19:16:50.2642759Z",
      "createdBy": "API.User",
      "uri": "/syncs/24"
    }

    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/24

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

    {
      "syncedInstanceUri": "/accounts/imports/43",
      "syncStartedAt": "2020-11-09T19:16:50.6700000Z",
      "syncEndedAt": "2020-11-09T19:16:52.5370000Z",
      "status": "success",
      "createdAt": "2020-11-09T19:16:50.2830000Z",
      "createdBy": "API.User",
      "uri": "/syncs/24"
    }

    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.