Using the Request Structured Data API

Follow the steps below to retrieve structured customer data from MXO that makes use of contextual information that you pass in. In the following example, we are going to request the name of a customer's preferred product within a supplied product category.

We've made the Request Structured Data API publicly available on Github. It's included as part of our Customer API. You can find it here:

Customer API

Step 1 - Add the Request Data Adapter to your Space

To enable MXO to use the contextual information passed into the API in an Eligibility Rule, create a Request Data Adapter.

The Request Data Adapter allows you to capture incoming parameters from both web URLs and API calls.

For more information, see To create a Request Data Adapter. DS - Create

Step 2 - Create an Eligibility Rule to find the value passed in on the API

Create an Eligibility Rule to determine the Proposition value passed in by the Request Structured Data API. Use the Request Data Adapter as the basis for an Eligibility Rule that finds the "proposition" parameter in the API request and returns the value passed on that request. DS - Create

Step 3 - Create a set of Eligibility Rules to determine the name of the Proposition with the highest interest count

Determining the name of the Proposition with the highest interest count requires two Eligibility Rules.

First, create an Eligibility Rule to determine the highest interest count among all Propositions whose full name includes the Proposition value passed in on the API request. DS - Create

Next, create an Eligibility Rule to determine the name of the Proposition that has the exact interest count returned by the previous Eligibility Rule. DS - Create

Step 4 - Add the "Preference from selected group" Eligibility Rule to a Pull Structure

Create a Pull Structure that includes the "Preference from selected group" Eligibility Rule. DS - Create

Step 5 - Publish your changes

The Structured Request API can only read information available in Structures that are published. Note that you must also publish all the Eligibility Rules referenced by your Pull Structure.

Step 6 - Request a Valid OAuth 2.0 token

Request a valid OAuth 2.0 token from MXO to use the Datastore API. Use your preferred API client to make the request, ensuring you provide the correct details.

Use the Client Credentials grant type when requesting an OAuth Token for the Data Export API.

For more information, see Request an OAuth 2.0 Token from MXO.

Step 7 - Use the Request Structured Data API to determine a customers current preferences

First pass in "ATM/" as the Proposition for whose children you want to find the highest interest count. This will provide you with the name of the ATM the customer currently uses the most.

Note: The trailing slash "/" is needed to indicate that you are interested only in the children of the ATM Proposition and not the ATM Proposition itself.

API Request

POST /one/oauth2/rt/api/3.1.0/customer/ONE-PFSPTU3IYX-5263/structure

{
	"customerContext": {
		"baseTouchpointUri": "atm://atm",
		"tid": "bec8c4ff-0fe8-cfb8-9a5d-8da5c6524aa7",
		"properties": [{
			"name": "proposition",
			"value": "ATM/"
		}]
	},
	"structureApiName": "preference"
}

API Response

{
	"structureApiName": "preference",
	"tid": "bec8c4ff-0fe8-cfb8-9a5d-8da5c6524aa7",
	"structure": {
		"preference": {
			"debug": {
				"input": "atm/",
				"count": 3.84
			},
			"propName": "/Services/ATM/ATM - Soho"
		}
	}
}

The API returns the value "ATM - Soho" as the customers current preferred ATM.

Next pass in the "Investment products/" Proposition. This time, MXO will return the name of the investment product with the highest interest count for the same customer.

API Request

POST /one/oauth2/rt/api/3.1.0/customer/ONE-PFSPTU3IYX-5263/structure

{
	"customerContext": {
		"baseTouchpointUri": "atm://atm",
		"tid": "bec8c4ff-0fe8-cfb8-9a5d-8da5c6524aa7",
		"properties": [{
			"name": "proposition",
			"value": "Investment products/"
		}]
	},
	"structureApiName": "preference"
}

API Response

{
	"structureApiName": "preference",
	"tid": "bec8c4ff-0fe8-cfb8-9a5d-8da5c6524aa7",
	"structure": {
		"preference": {
			"debug": {
				"input": "Investment products/",
				"count": 8.67
			},
			"propName": "/Investment products/Bonds/Bonds - 3yr"
		}
	}
}

The API returns the value "Bonds - 3yr" as the customers current preferred investment product.

Step 8 - Use the Monitor to confirm the returned results are correct

You can check that the results returned by the API are correct using the Monitor in MXO .

In ONE, navigate to Test > Monitor. Ensure you are monitoring the same TID used on the original API request.

DS - Create

In the Data panel, select Proposition Activity Counts as the data you wish to view.

DS - Create