With the Oracle Eloqua 478/479 release, lead scoring models and fields are coming to the Bulk API. I am going to walk through an end to end scenario with examples, but before I do that here are some of the highlights:

  • Lead scoring models and their corresponding lead scoring fields will be discoverable via the Bulk API
  • Lead scoring fields will be available to be used in Bulk API contact export definitions
    • There could only be one lead scoring model used per contact export definition
  • Each lead scoring model has three lead scoring fields available:
    • Rating
    • Profile Score
    • Engagement Score
  • Lead scoring fields can be used in contact export filter statements

 

With the key takeaways highlighted, let's now take a look at this new functionality in action. I'm going to walk through finding a lead scoring model, using those lead scoring fields in a contact export definition, and completing the scenario by retrieving some contacts. Along the way we'll also use a lead scoring field in a filter statement and, as a bonus, I'll be highlighting an additional improvement in regards to contact exports. Total FOMO should now be in place!

 

Let's start by retrieving two lead scoring models:

 

Request

GET /API/Bulk/2.0/contacts/scoring/models?limit=2

Response

200 OK

 

{

  "items": [

    {

      "name": "Test 1",

      "status": "Draft",

      "id": 1,

      "fields": [

        {

          "name": "Rating",

          "statement": "{{Contact.LeadScore.Model[1].Rating}}",

          "dataType": "string"

        },

        {

          "name": "ProfileScore",

          "statement": "{{Contact.LeadScore.Model[1].ProfileScore}}",

          "dataType": "number"

        },

        {

          "name": "EngagementScore",

          "statement": "{{Contact.LeadScore.Model[1].EngagementScore}}",

          "dataType": "number"

        }

      ],

      "uri": "/contacts/scoring/models/1",

      "createdBy": "Lou.Patrick",

      "updatedBy": "Lou.Patrick",

      "createdAt": "2015-01-15T18:44:58.9930000Z",

      "updatedAt": "2015-07-02T18:03:19.1930000Z"

    },

    {

      "name": "Test 2",

      "status": "Draft",

      "id": 2,

      "fields": [

        {

          "name": "Rating",

          "statement": "{{Contact.LeadScore.Model[2].Rating}}",

          "dataType": "string"

        },

        {

          "name": "ProfileScore",

          "statement": "{{Contact.LeadScore.Model[2].ProfileScore}}",

          "dataType": "number"

        },

        {

          "name": "EngagementScore",

          "statement": "{{Contact.LeadScore.Model[2].EngagementScore}}",

          "dataType": "number"

        }

      ],

      "uri": "/contacts/scoring/models/2",

      "createdBy": "Lou.Patrick",

      "updatedBy": "Lou.Patrick",

      "createdAt": "2015-01-15T18:45:09.9930000Z",

      "updatedAt": "2015-07-02T18:18:01.6570000Z"

    }

  ],

  "totalResults": 6,

  "limit": 2,

  "offset": 0,

  "count": 2,

  "hasMore": true

}

 

I do not see the lead scoring model I'm looking for; however, I see there are four more lead scoring models. I could remove the limit and return all lead scoring models but I know the name of the lead scoring model I want so let's use a query parameter to retrieve a lead scoring model by name and, because I'm not sure on the exact name, we'll use some wildcards:

 

Request

GET /API/Bulk/2.0/contacts/scoring/models?q="name=*Oscar*"

Response

200 OK

 

{

  "items": [

    {

      "name": "Oscar Cleaning",

      "status": "Active",

      "id": 6,

      "fields": [

        {

          "name": "Rating",

          "statement": "{{Contact.LeadScore.Model[6].Rating}}",

          "dataType": "string"

        },

        {

          "name": "ProfileScore",

          "statement": "{{Contact.LeadScore.Model[6].ProfileScore}}",

          "dataType": "number"

        },

        {

          "name": "EngagementScore",

          "statement": "{{Contact.LeadScore.Model[6].EngagementScore}}",

          "dataType": "number"

        }

      ],

      "uri": "/contacts/scoring/models/6",

      "createdBy": "Lou.Patrick",

      "updatedBy": "Lou.Patrick",

      "createdAt": "2016-03-22T17:20:54.6100000Z",

      "updatedAt": "2016-03-22T18:20:39.3000000Z"

    }

  ],

  "totalResults": 1,

  "limit": 1000,

  "offset": 0,

  "count": 1,

  "hasMore": false

}

 

There's the one I'm looking for. Now let's create a contact export definition using the lead scoring fields for the Oscar Cleaning lead scoring model:

250_fields.png

Request

POST /API/Bulk/2.0/contacts/exports

Request - Body

{

  "name": "Contact Lead Score Export - Oscar Cleaning",

  "fields": {

    "EmailAddress": "{{Contact.Field(C_EmailAddress)}}",

    "FirstName": "{{Contact.Field(C_FirstName)}}",

    "LastName": "{{Contact.Field(C_LastName)}}",

    "Rating": "{{Contact.LeadScore.Model[6].Rating}}",

    "Profile": "{{Contact.LeadScore.Model[6].ProfileScore}}",

    "Engagement": "{{Contact.LeadScore.Model[6].EngagementScore}}",

    "AcademyAwards": "{{Contact.Field(C_Academy_Awards1)}}"

  }

}

Response

201 Created

 

{

  "name": "Contact Lead Score Export - Oscar Cleaning",

  "fields": {

    "EmailAddress": "{{Contact.Field(C_EmailAddress)}}",

    "FirstName": "{{Contact.Field(C_FirstName)}}",

    "LastName": "{{Contact.Field(C_LastName)}}",

    "Rating": "{{Contact.LeadScore.Model[6].Rating}}",

    "Profile": "{{Contact.LeadScore.Model[6].ProfileScore}}",

    "Engagement": "{{Contact.LeadScore.Model[6].EngagementScore}}",

    "AcademyAwards": "{{Contact.Field(C_Academy_Awards1)}}"

  },

  "dataRetentionDuration": "PT12H",

  "uri": "/contacts/exports/5",

  "createdBy": "Lou.Patrick",

  "createdAt": "2016-03-22T19:22:05.2099774Z",

  "updatedBy": "Lou.Patrick",

  "updatedAt": "2016-03-22T19:22:05.2099774Z"

}

 

With our uri in hand, we are now ready to create the sync:

 

Request

POST /API/Bulk/2.0/syncs

Request - Body

{

  "syncedInstanceUri": "/contacts/exports/5"

}

Response

201 Created

 

{

  "syncedInstanceUri": "/contacts/exports/5",

  "status": "pending",

  "createdAt": "2016-03-22T19:34:44.7980550Z",

  "createdBy": "Lou.Patrick",

  "uri": "/syncs/2"

}

 

Ideally we'd be using the callbackUrl parameter to allow Eloqua to alert us when the sync is complete. For simplicity of demonstration, I'll GET the sync details to confirm it was successful:

 

Request

GET /API/Bulk/2.0/syncs/2

Response

200 OK

 

{

  "syncedInstanceUri": "/contacts/exports/5",

  "syncStartedAt": "2016-03-22T19:34:47.2570000Z",

  "syncEndedAt": "2016-03-22T19:34:48.5000000Z",

  "status": "success",

  "createdAt": "2016-03-22T19:34:45.0030000Z",

  "createdBy": "Lou.Patrick",

  "uri": "/syncs/2"

}

 

Success! Now it's time to retrieve the data:

 

Request

GET /API/Bulk/2.0/syncs/2/data

Response

200 OK

 

{

  "totalResults": 13,

  "limit": 1000,

  "offset": 0,

  "count": 13,

  "hasMore": false,

  "items": [

    {

      "EmailAddress": "test1234@test.com",

      "FirstName": "",

      "LastName": "",

      "Rating": "D4",

      "Profile": "0",

      "Engagement": "0",

      "AcademyAwards": ""

    },

    {

      "EmailAddress": "lou.patrick@oracle.com",

      "FirstName": "Lou",

      "LastName": "Patrick",

      "Rating": "D4",

      "Profile": "0",

      "Engagement": "0",

      "AcademyAwards": ""

    },

    {

      "EmailAddress": "test12@test.com",

      "FirstName": "Test12",

      "LastName": "",

      "Rating": "D4",

      "Profile": "0",

      "Engagement": "0",

      "AcademyAwards": ""

    },

    {

      "EmailAddress": "test1234@test1234.com",

      "FirstName": "",

      "LastName": "",

      "Rating": "D4",

      "Profile": "0",

      "Engagement": "0",

      "AcademyAwards": ""

    },

    {

      "EmailAddress": "12321321312test@test.com",

      "FirstName": "",

      "LastName": "",

      "Rating": "D4",

      "Profile": "0",

      "Engagement": "0",

      "AcademyAwards": ""

    },

    {

      "EmailAddress": "123456@test.com",

      "FirstName": "",

      "LastName": "",

      "Rating": "D4",

      "Profile": "0",

      "Engagement": "0",

      "AcademyAwards": ""

    },

    {

      "EmailAddress": "whoopi@egot.com",

      "FirstName": "Whoopi",

      "LastName": "Goldberg",

      "Rating": "B1",

      "Profile": "70",

      "Engagement": "100",

      "AcademyAwards": "1.0000"

    },

    {

      "EmailAddress": "streep@gmail.com",

      "FirstName": "Meryl",

      "LastName": "Streep",

      "Rating": "A3",

      "Profile": "100",

      "Engagement": "30",

      "AcademyAwards": "3.0000"

    },

    {

      "EmailAddress": "thanks@yahoo.com",

      "FirstName": "Tom",

      "LastName": "Hanks",

      "Rating": "A4",

      "Profile": "80",

      "Engagement": "0",

      "AcademyAwards": "2.0000"

    },

    {

      "EmailAddress": "cruise@gmail.com",

      "FirstName": "Tom",

      "LastName": "Cruise",

      "Rating": "D1",

      "Profile": "0",

      "Engagement": "100",

      "AcademyAwards": ""

    },

    {

      "EmailAddress": "arnold@schawrz.com",

      "FirstName": "Arnold",

      "LastName": "Schwarzenegger",

      "Rating": "D2",

      "Profile": "0",

      "Engagement": "70",

      "AcademyAwards": ""

    },

    {

      "EmailAddress": "jack@gmail.com",

      "FirstName": "Jack",

      "LastName": "Nicholson",

      "Rating": "A1",

      "Profile": "100",

      "Engagement": "100",

      "AcademyAwards": "3.0000"

    },

    {

      "EmailAddress": "nats@yahoo.com",

      "FirstName": "Natalie",

      "LastName": "Portman",

      "Rating": "B4",

      "Profile": "70",

      "Engagement": "0",

      "AcademyAwards": "1.0000"

    }

  ]

}

 

There are not many contacts in this test instance but there are some clear test contacts and also some contacts we'd want to remove as they do not have any Academy Awards. Next, we'll create a new contact export definition and filter on the Profile lead scoring field, removing all contacts from our export with a Profile value of "0":

 

Request

POST /API/Bulk/2.0/contacts/exports

Request - Body

{

  "name": "Contact Lead Score Export - Oscar Cleaning - Filtered",

  "fields": {

    "EmailAddress": "{{Contact.Field(C_EmailAddress)}}",

    "FirstName": "{{Contact.Field(C_FirstName)}}",

    "LastName": "{{Contact.Field(C_LastName)}}",

    "Rating": "{{Contact.LeadScore.Model[6].Rating}}",

    "Profile": "{{Contact.LeadScore.Model[6].ProfileScore}}",

    "Engagement": "{{Contact.LeadScore.Model[6].EngagementScore}}",

    "AcademyAwards": "{{Contact.Field(C_Academy_Awards1)}}"

  },

  "filter": "'{{Contact.LeadScore.Model[6].ProfileScore}}' > '0'"

}

Response

201 Created

 

{

  "name": "Contact Lead Score Export - Oscar Cleaning - Filtered",

  "fields": {

    "EmailAddress": "{{Contact.Field(C_EmailAddress)}}",

    "FirstName": "{{Contact.Field(C_FirstName)}}",

    "LastName": "{{Contact.Field(C_LastName)}}",

    "Rating": "{{Contact.LeadScore.Model[6].Rating}}",

    "Profile": "{{Contact.LeadScore.Model[6].ProfileScore}}",

    "Engagement": "{{Contact.LeadScore.Model[6].EngagementScore}}",

    "AcademyAwards": "{{Contact.Field(C_Academy_Awards1)}}"

  },

  "filter": "'{{Contact.LeadScore.Model[6].ProfileScore}}' > '0'",

  "dataRetentionDuration": "PT12H",

  "uri": "/contacts/exports/6",

  "createdBy": "Lou.Patrick",

  "createdAt": "2016-03-22T20:16:32.6099108Z",

  "updatedBy": "Lou.Patrick",

  "updatedAt": "2016-03-22T20:16:32.6099108Z"

}

 

We'll skip over showing examples for creating the sync and confirming it was successful, as it's identical to the examples above. From creating the sync the resulting uri is "/syncs/3". Let's jump to retrieving data from our filtered contact export definition sync:

 

Request

GET /API/Bulk/2.0/syncs/3/data

Response

200 OK

 

{

  "totalResults": 5,

  "limit": 1000,

  "offset": 0,

  "count": 5,

  "hasMore": false,

  "items": [

    {

      "EmailAddress": "whoopi@egot.com",

      "FirstName": "Whoopi",

      "LastName": "Goldberg",

      "Rating": "B1",

      "Profile": "70",

      "Engagement": "100",

      "AcademyAwards": "1.0000"

    },

    {

      "EmailAddress": "streep@gmail.com",

      "FirstName": "Meryl",

      "LastName": "Streep",

      "Rating": "A3",

      "Profile": "100",

      "Engagement": "30",

      "AcademyAwards": "3.0000"

    },

    {

      "EmailAddress": "thanks@yahoo.com",

      "FirstName": "Tom",

      "LastName": "Hanks",

      "Rating": "A4",

      "Profile": "80",

      "Engagement": "0",

      "AcademyAwards": "2.0000"

    },

    {

      "EmailAddress": "jack@gmail.com",

      "FirstName": "Jack",

      "LastName": "Nicholson",

      "Rating": "A1",

      "Profile": "100",

      "Engagement": "100",

      "AcademyAwards": "3.0000"

    },

    {

      "EmailAddress": "nats@yahoo.com",

      "FirstName": "Natalie",

      "LastName": "Portman",

      "Rating": "B4",

      "Profile": "70",

      "Engagement": "0",

      "AcademyAwards": "1.0000"

    }

  ]

}

 

Now we have filtered results including only contacts that have at least one Academy Award. That completes the walk through of the lead scoring capabilities coming to the Bulk API. So now I bet everyone wants to mark their calendars with the date 478/479 will arrive for them!

 

When will I receive the 478/479 release? Visit the Oracle Eloqua Release Center to view roll out dates.

 

How about documentation? When version 478/479 is rolled out to POD2, the Oracle Eloqua Developer Help Center will be updated with the new endpoints and examples. (Documentation now updated: Lead scoring models)

 

Interested in more related to Eloqua APIs and the 478/479 release? Take a look at the Developer Release Notes - 478/479.

 

Happy coding with the Eloqua APIs and see you around Code It!