Retrieving app records using the bulk API

You can get notified when contacts or custom objects arrive to your app within a campaign or program. Eloqua will send your app a notification call in the form of a HTTP POST request that includes data about the contacts or custom object records. This is accomplished by supplying a Notification URL during service registration for action and decision services.

You control the maximum amount of contacts or custom object records sent per notification call by setting the Records per Notification option during service registration.

An image of the service setting page, where Records per Notification is highlighted

When Records per Notification is greater than 0, the HTTP POST request sent to the app will include data for the contacts or custom objects within the items array.

POST https://example.com/awesomeapp/action/notify?instance={InstanceId}&asset={AssetId}&execution={ExecutionId}

{
    "offset" : 0,
    "limit" : 1000,
    "totalResults" : 2,
    "count" : 2,
    "hasMore" : false,
    "items" :
    [
       {
          "ContactID" : "1",
          "EmailAddress" : "fred@example.com",
          "field1" : "stuff",
          "field2" : "things",
          "field3" : "et cetera"
       },
       {
          "ContactID" : "2",
          "EmailAddress" : "john@example.com",
          "field1" : "more stuff",
          "field2" : "other things",
          "field3" : "and so on"
       }
    ]
}

This request can get large, especially if the maximum records sent per notification is 5,000 for example. It is possible instead for app developers to select the maximum amount of Records per Notification to 0 and retrieve records on their own.

Setting records per notification to 0

If Records per Notification is set to 0, the notification call is sent with no data within the items property. The developer must then retrieve the records within the step using a separate bulk API export. This enables developers to control when and how quickly records are retrieved.

This tutorial will walkthrough the flow of having Records per Notification set to 0 and guiding developers through the flow of retrieving records within a step using a separate bulk API export.

Eloqua app service settings

Before we walkthrough how to respond to the notification call, note the Eloqua app service settings we will be using for the examples in this tutorial.

  • Note the notification URL contains the 3 template parameters: InstanceId , AssetId, and ExecutionId.
  • Records per Notification is set to 0.

To edit your service settings, navigate to Settings > AppCloud Developer and edit your service's settings.

Notification call

When contacts or custom objects arrive in the step, Eloqua sends a HTTP POST request to the app's Notification URL.

POST https://example.com/awesomeapp/action/notify?instance=f82d50cd-86a9-4fca-b37e-4ec9a98b0339&asset=456&execution=12345

{
    "offset" : 0,
    "limit" : 1000,
    "totalResults" : 0,
    "count" : 0,
    "hasMore" : false,
    "items" : []
}

Developers must then create a bulk API export definition using the data from Eloqua's call to the Notification URL.

Using contacts as an example, let's walkthrough how to form our bulk API export definition to retrieve the records.

Request 

POST https://secure.p03.eloqua.com/api/bulk/2.0/contacts/exports
 
{
    "name": "Awesome App Contact Export - f82d50cd-86a9-4fca-b37e-4ec9a98b0339 - 12345",
    "fields": {
        "emailAddress": "{{Contact.Field(C_EmailAddress)}}"
    },
	"filter": "STATUS('{{ActionInstance(f82d50cd86a94fcab37e4ec9a98b0339).Execution[12345]}}') = 'pending'" 
}

Response 

{
    "name": "Awesome App Contact Export - f82d50cd-86a9-4fca-b37e-4ec9a98b0339 - 12345",
    "fields": {
        "emailAddress": "{{Contact.Field(C_EmailAddress)}}"
    },
    "dataRetentionDuration": "PT12H",
    "uri": "/contacts/exports/55",
    "createdBy": "API.User",
    "createdAt": "2018-08-19T20:51:28.8201911Z",
    "updatedBy": "API.User",
    "updatedAt": "2018-08-19T20:51:28.8201911Z"
}

Next, create a sync using the export definition uri.

Request 

POST https://secure.p03.eloqua.com/api/bulk/2.0/syncs
 
{
   "syncedInstanceUri" : "/contacts/exports/55",
   "callbackURL" : "https://www.example.com"
}

Response 

{
    "syncedInstanceUri":"/contacts/exports/55",
    "callbackUrl":"http://www.example.com",
    "status":"pending",
    "createdAt":"2018-09-25T18:08:32.3485942Z",
    "createdBy":"API.User",
    "uri":"/syncs/66100"
}

The sync status will progress. Retrieve the sync to check the status of the sync.

Request 

GET https://secure.p03.eloqua.com/api/bulk/2.0/sync/66100

Response 

{
  "syncedInstanceURI": "/contacts/exports/55",
  "syncStartedAt": "2014-01-01T13:59:07.1375620Z",
  "syncEndedAt": "2014-01-01T13:59:14.1375620Z",
  "status": "success",
  "createdAt": "2014-01-01T13:59:07.1375620Z",
  "createdBy": "DocsExample",
  "uri": "/syncs/6"
}

After the sync has completed and the status is success, the last step is to retrieve the sync data.

Request 

GET https://secure.p03.eloqua.com/api/bulk/2.0/syncs/66100/data

Response 

{
  "totalResults": 1,
  "limit": 0,
  "offset": 0,
  "count": 0,
  "hasMore": true,
  "items": [
    {
      "email": "john.snow@example.com"
    }
  ]
}

Using the data

Your app will likely want to use the records for a specific purpose, after this is done, you can import the data into Eloqua.

Importing the data into Eloqua

Start by creating a bulk import definition, setting the status to complete to import data. For this example, we will demonstrate using a contact import definition, where our service is an action service and its instance GUID is f82d50cd-86a9-4fca-b37e-4ec9a98b0339.

If there is no data to import, and you only need to update a record's status, you can update a record's status without performing an import by creating a contact sync action definition.

Warning: When referencing service instances, you must transmit the GUID without dashes. The bulk API will error if you transmit the GUID with the dashes.

Create a contact import definition.

Request 

POST https: //secure.p03.eloqua.com/api/bulk/2.0/contacts/imports
{
  "name": "Awesome App Contact Import - f82d50cd-86a9-4fca-b37e-4ec9a98b0339 - 12345",
  "updateRule": "always",
  "fields": {
    "emailAddress": "{{Contact.Field(C_EmailAddress)}}"
  },
  "syncActions": [
    {
      "destination": "{{ActionInstance(f82d50cd86a94fcab37e4ec9a98b0339).Execution[12345]}}",
      "action": "setStatus",
      "status": "complete"
    }
  ],
  "identifierFieldName": "emailAddress"
}

Eloqua's response will be a 201 Created response that includes a uri parameter, which you can use to identify the import.

Response 

{
  "name": "Awesome App Contact Import - f82d50cd-86a9-4fca-b37e-4ec9a98b0339 - 12345",
  "updateRule": "always",
  "fields": {
    "emailAddress": "{{Contact.Field(C_EmailAddress)}}"
  },
  "identifierFieldName": "emailAddress",
  "syncActions": [
    {
      "destination": "{{ActionInstance(f82d50cd86a94fcab37e4ec9a98b0339).Execution[12345]}}",
      "action": "setStatus",
      "status": "complete"
    }
  ],
  "isSyncTriggeredOnImport": false,
  "isUpdatingMultipleMatchedRecords": false,
  "uri": "/contacts/imports/6",
  "createdBy": "API.User",
  "createdAt": "2018-03-06T13:59:00.6600046Z",
  "updatedBy": "API.User",
  "updatedAt": "2018-03-06T13:59:00.6600046Z"
}

Send Eloqua the import data using the uri:

Request 

POST https://secure.p03.eloqua.com/api/bulk/2.0/contacts/imports/6/data
[
  {
    "emailAddress": "john.snow@example.com"
  }
]

Eloqua's response will be a 204 No Content indicating that the data upload was successful.

Learn more

Oracle Eloqua Bulk API