Sync actions to Eloqua

To sync actions to Eloqua using the bulk API:

  1. Create the sync action definition.
  2. Upload the data to perform sync actions on into a temporary staging area.
  3. Synchronize the data from the staging area into Eloqua.

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

To sync actions to Eloqua

  1. Create the sync action definition.

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

    Definition parameters

    Name Required/Optional Description
    nameRequiredThe name of your sync action for reference.
    fieldsRequired

    This is the most important parameter in your sync action definition. It defines which field to uniquely match records to perform sync actions for the given Eloqua record type. The field parameter is made up of a name value and a field statement, for example: "ContactId":"{{Contact.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 one of the following fields based on the record type:

    • Contacts
      • {{Contact.Id}}
      • {{Contact.Field(C_EmailAddress)}}
      • {{Contact.Field(ContactIDExt)}}
    • Accounts
      • {{Account.Id}}
      • {{Account.Field(M_CompanyName)}}
      • {{Account.Field(CompanyIDExt)}}
    • Custom Objects
      • {{CustomObject[customObjectId].Id}}
      • {{CustomObject[customObjectId].ExternalId}}
    identifierFieldNameRequiredThis parameter is used to select the field to uniquely match records to perform sync actions. It should match the field name as defined in the above fields parameter.
    isSyncTriggeredOnImportOptional A Boolean parameter specifying whether the sync is triggered automatically upon import. If set to true, the Bulk API automatically syncs your data to Eloqua when you upload it to the staging area. If set to false, you must manually create the sync operation that syncs your data to 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.
    syncActionsRequired Sync Actions are parameters that that specify actions Eloqua should take for this sync action definition. Up to ten sync actions can be included within one sync action definition. Learn more about sync actions.

    The following sync action definition will perform sync actions to add/remove contacts to/from lists, subscribe globally, and subcribe/unsubscribe contacts for email groups using the Eloqua Email Address contact record field, C_EmailAddress. There are different sync actions and endpoints depending on whether you're creating an sync action definition for Accounts, Contacts, Custom objects, or Email addresses.

    Note: If you are not updating fields, the sync action definition endpoints should be used to perform actions in Eloqua 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. Creating an import definition is required if you are updating fields for the Eloqua record type. Learn more about Importing data into Eloqua.

    Request:

    POST /bulk/2.0/contacts/syncactions

    Request body:

    {
    "name": "Docs Sync Action Example",
    "fields": {
        "emailAddress": "{{Contact.Field(C_EmailAddress)}}"
    },
    "identifierFieldName": "emailAddress",
    "syncActions": [
        {
            "action": "add",
            "destination": "{{ContactList[138]}}"
        },
        {
            "action": "remove",
            "destination": "{{ContactList[137]}}"
        },
        {
            "action": "setStatus",
            "destination": "{{GlobalSubscribe}}",
            "status": "subscribed"
        },
        {
            "action": "setStatus",
            "destination": "{{EmailGroup[1]}}",
            "status": "subscribed"
        },
        {
            "action": "setStatus",
            "destination": "{{EmailGroup[2]}}",
            "status": "unsubscribed"
        }
    ],
    "isSyncTriggeredOnImport": "false"
}

    A successful response will include the sync action definition's name, fields, identifierFieldName, syncActions, isSyncTriggeredOnImport, 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 Sync Action Example",
	"fields":{
		"emailAddress":"{{Contact.Field(C_EmailAddress)}}"
	},
	"identifierFieldName":"emailAddress",
	"syncActions":[
		{
			"action":"add",
			"destination":"{{ContactList[138]}}"
		},
		{
			"action":"remove",
			"destination":"{{ContactList[137]}}"
		},
		{
			"action":"setStatus",
			"destination":"{{GlobalSubscribe}}",
			"status":"subscribed"
		},
		{
			"action":"setStatus",
			"destination":"{{EmailGroup[1]}}",
			"status":"subscribed"
		},
		{
			"action":"setStatus",
			"destination":"{{EmailGroup[2]}}",
			"status":"unsubscribed"
		}
	],
	"isSyncTriggeredOnImport":"false",
	"uri":"/contacts/syncActions/410",
	"createdBy":"Docs.Example",
	"createdAt":"2024-12-17T23:23:19.7570000Z",
	"updatedBy":"Docs.Example",
	"updatedAt":"2024-12-17T23:23:19.7570000Z"
}

    You will use the returned uri parameter to upload data to perform sync actions on into Eloqua.

  2. Upload the data: Once you have your sync action definition's uri, you can use it to upload the incoming data to perform sync actions on.

    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/syncActions/410/data

    Request body:

    [
	{
		"emailAddress":"juan@example.com"
	},
	{
		"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 a sync action 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 sync action definition before syncing. It is recommended to sync sync action data 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/syncActions/410"
}

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

    {
	"syncedInstanceUri":"/contacts/syncActions/410",
	"status":"pending",
	"createdAt":"2024-12-17T23:54:24.4500000Z",
	"createdBy":"Docs.Example",
	"uri":"/syncs/18089"
}

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

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

    {
	"syncedInstanceUri":"/contacts/syncActions/410",
	"syncStartedAt":"2024-12-17T23:54:24.6500000Z",
	"syncEndedAt":"2024-12-17T23:54:24.9400000Z",
	"status":"success",
	"createdAt":"2024-12-17T23:54:24.4500000Z",
	"createdBy":"Docs.Example",
	"uri":"/syncs/18089"
}

    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.