Site Optimization is a licensed part of the Engagement solution that will automatically recommend the right, high-value content and goal pages for each visitor using Artificial Intelligence and machine learning to increase engagement and accelerate the path to conversion.
The Site Optimization API is responsible for serving the recommendations that fill the site optimization recommendation window.
NOTE: Keep in mind that implementing a custom API solution involves a significant amount of work for your team. For faster, more efficient implementation we highly recommend that you instead use our standard integration via Demandbase Tag.
Prerequisites
- The Demandbase Tag must have been live on the website where recommendations are being made for more than 2 weeks. The model will be trained after tens and thousands of page views. If you need help installing your Demandbase Tag please contact your CSM or our technical support team at support@demandbase.com.
- You must use your Demandbase Tag API Key for the Site Optimization API. This is found in the Network request when Demandbase Tag runs on your website.
- The Site Optimization model must have been successfully run. To check if it runs successfully you should see recommendations in the preview step of the Site Optimization product. If you are getting an error related to this, please contact support@demandbase.com.
Example Request
The are 3 main parameters:
- The Demandbase SID (Demandbase company ID from the Company API)
- The base64 encoded Page URL
- Your Demandbase Tag API Key
Example URL:
The three main parameters are highlighted in yellow.
https://site-optimization-api.company-target.com/recommend/ 1234566 ?page= aHR0cHM6Ly93d3cuZGVtYW5kYmFzZS5jb20v &apiKey= alphanumerickey123
Example Response
//HTTP 200
{
"rid": "jf5haxntTJmTVPpILEYTJw",
"should_display": true,
"recommendations": [
{
"page": "www.demandbase.com/ebook/account-based-marketing-the-key-to-b2b-success?db-siteopt-rid=jf5haxntTJmTVPpILEYTJw",
"image": "https://www.demandbase.com/wp-content/uploads/resources-thumbnail-ebook-generic-image.jpg",
"title": "Account-Based Marketing: The Key to B2B Success",
"probability": 0.061109114708916126,
"expected_value": 2.418023084591552,
"score": 0.14776325004511234,
"conversion_pages": [
{
"conversion_page": "www.demandbase.com/ebook/account-based-marketing-the-key-to-b2b-success",
"prob_current": 0.043516029510918625,
"prob_next": 1.0452581939500543,
"prob_increase_percentage": 2302
},
{
"conversion_page": "www.demandbase.com/ebook/b2b-marketers-guide-account-based-marketing",
"prob_current": 0.007600901381545576,
"prob_next": 0.12631249511237413,
"prob_increase_percentage": 1562
},
{
"conversion_page": "www.demandbase.com/ebook/account-based-marketing-fundamentals-every-b2b-marketer-must-know",
"prob_current": 0.010444291041493019,
"prob_next": 0.12118793017898015,
"prob_increase_percentage": 1060
}
],
"all_negative": false
},
{
"page": "www.demandbase.com/resources/events?db-siteopt-rid=jf5haxntTJmTVPpILEYTJw",
"image": "https://www.demandbase.com/wp-content/uploads/default-ebook-webinar-featured-image.jpg",
"title": "Events & Webinars",
"probability": 0.08430272903519226,
"expected_value": 0.802242591154425,
"score": 0.06763123978258201,
"conversion_pages": [
{
"conversion_page": "www.demandbase.com/webinar/abm-team-sport",
"prob_current": 0.03336430201557014,
"prob_next": 0.14394467231724659,
"prob_increase_percentage": 331
},
{
"conversion_page": "www.demandbase.com/ebook/abm-team-sport",
"prob_current": 0.015241847022255948,
"prob_next": 0.06485992385455719,
"prob_increase_percentage": 326
},
{
"conversion_page": "www.demandbase.com/webinar/abm-impact-blended-approach",
"prob_current": 0.016828193365295403,
"prob_next": 0.025558355669193622,
"prob_increase_percentage": 52
}
],
"all_negative": false
}
],
"sid": 5347713,
"current_page": "www.demandbase.com",
"logo": "https://d2b50tjqdt4ebt.cloudfront.net/media/companies/196338",
"company_name": "Demandbase",
"pageviews_30": 87,
"pageviews_60": 148,
"pageviews_90": 295,
"pageviews_all": 543,
"sessions_30": 17,
"sessions_60": 34,
"sessions_90": 70,
"sessions_all": 116
}
Request Parameters
| Name | Data Type | Description | Example |
|---|---|---|---|
| sid | Integer | This identifies the company, and as an identifier specific to Demandbase. It corresponds to the demandbase_sid response field from the IP API. | /recommend/ 5347713 ?page=aHR0cHM6Ly93d3cuZGVtYW5kYmFzZS5jb20v&apiKey=3cb1dcb19f551 |
| page | String | The page for which to serve recommendations. The URL should contain the protocol and it should be base64 encoded. | /recommend/5347713?page= aHR0cHM6Ly93d3cuZGVtYW5kYmFzZS5jb20v &apiKey=3cb1dcb19f551 |
| apiKey | String | This is your primary Demandbase API key. You can find it in your IP API requests made by Demandbase Tag, and you can also ask us for this value. Ask for your Analytics Enabled API key. | /recommend/5347713?page=aHR0cHM6Ly93d3cuZGVtYW5kYmFzZS5jb20v&apiKey= 3cb1dcb19f551 |
| solveConversionProbabilities | Boolean | This value determines whether or not the conversion_pages field will be populated in each recommendation. It is expensive to calculate so we require an explicit request to return it. Default value is false. | /recommend/5347713?page=aHR0cHM6Ly93d3cuZGVtYW5kYmFzZS5jb20v&apiKey=3cb1dcb19f551&solveConversionProbabilities= true |
Response fields
Top Level Response Object
| Name | Data Type | Description | Example |
|---|---|---|---|
| rid | String | A unique recommendation id that identifies the given instance of recommendations. It is generated for every set of recommendations. | "rid": "y1GsZW8wSJ2UMs6WnVUsjw", |
| should_display | Boolean | This field determines whether recommendations should be displayed on the current page, or not. It is calculated based on the set of rules, specified in Demandbase setup console (Engagement -> Site Optimization -> Display Options) | "should_display": true |
| recommendations | Array[Recommendation Object] | The top level collection responsible for holding the group of recommendations | "recommendations": [{...}] |
| sid | Integer | See request parameters. It will always be the same as this value. | "sid": 3415304, |
| current_page | String | The page for which we are serving recommendations. This will be a standardized version of the "page" request parameter. The protocol and query string are removed. | "current_page": "www.demandbase.com" |
| logo | String | A URL to the logo we have identified for the company identified by the sid request parameter. | "logo": "https://d2b50tjqdt4ebt.cloudfront.net/media/companies/196338", |
| company_name | String | The name of the company identified by the sid request parameter | "company_name": "Demandbase" |
Recommendation Object
|
Name
|
Data Type
|
Description
|
Example
|
|
|---|---|---|---|---|
| page | String | A standardized URL that points to the recommended page. The protocol and query string are removed, and db-siteopt-rid will be added for tracking purposes. This identifier is the same as the "rid" response field |
|
|
| image | String | A URL that points to the image that best represents the page as determined by our algorithm, which takes many features of the page into consideration. | ||
| title | String | The cleand-up page title. Our algorithm automatiocally removes page title segments that repeat too often, in order to remove common title formats like "Actual Page Title | Company Name". In this example, our cleaned-up page title would be "Actual Page Title". |
|
|
| probability | Float | The normalized output of the page transition model's score for this recommendation. This value correlates with how likely we believe the user is to visit this page. |
|
|
| expected_value | Float | The value from the solution of a Bellman equation for a reward vector that gives a terminal reward of 0.1 for regular pages, 0 for blacklist pages, and 1 for conversion pages (see personalization.demandbase.com/setup/pages for these definitions). Due to this definition, it can also loosely be interpreted as the number of conversion pages we expect the user to visit if they visit this page. |
|
|
| score | Float | The probability multiplied by the expected_value. This is what determines the default sort order for recommendations. |
|
|
| conversion_pages | Array[Conversion Page Object] | The collection responsible for holding the top 3 conversion pages that relate to the recommended page. It is only populated if solveConversionProbabilities set on the request parameter is true. |
|
Conversion Page Object
|
Name
|
Data Type
|
Description
|
Example Use
|
||
|---|---|---|---|---|---|
| conversion_page | String | The standardized conversion page URL |
|
||
| prob_current | Float | A value that correlates to the likelihood that the user visits the given conversion_page given that they are currently viewing the current_page. It is the value as determined by the solution of a Bellman equation for a reward vector where this page is the only page gives any terminal reward (1). |
|
||
| prob_next | Float | A value which correlates to the likelihood that the user visits conversion_page (at any point in their session) given that they are currently viewing the recommended page. |
|
||
| prob_increase_percentage | Float |
Essentially
|
|
DISCLAIMER: Any apparent response fields that are not described in this document are temporary and for diagnostic purposes. Do not depend on them as they may be removed at any time. Here is an example of such a field:
"pageviews_30": 87,Defensive Coding
API response data attributes will vary. While we will do our best to inform our customers of changes that we believe will impact them, do not code against an exact count of properties in the response or expect all properties at all time, we expect to remove or introduce new properties and your code should handle all scenarios defensively.