Eloqua - How to Use Bulk Upsert with Custom Objects

This guide provides some clarification around using Eloqua's bulk API in conjunction with their custom objects.

There are typically three types of Bulk Upload Jobs:  

  • Update: Update all records based off of a unique identifierFieldName.
  • Insert: Create new records based off of the data in the bulk job. 
  • Upsert: Combination of both. Will update a record using the identifierFieldName, but if it cannot find a record with a matching identifierFieldName it will create the record. 

Eloqua's native bulk always performs an upsert, therefore "identifierFieldName" is required. 

Eloqua Custom Objects always return data through the CustomObjectData resource. At its root, this resource returns metadata such as createdAt and type. However, this object also contains a custom key that contains your custom field data:

"custom": {
      "99": "Sample Description 1111",
      "100": "Form Submit Activity",
      "101": "RobotTester@example.com",
      "102": "101"
    }

Each of the number keys correlates to a custom field that you have built for your custom object. For example, 101 relates to the email field. Therefore, when building your bulk query, as part of the metadata you have to pass an "identifierFieldName" as the field ID and not the field name. In this case we would use {"identifierFieldName":"101"}.