Deliver offers using the Decisions API

Offer Decisioning is a collection of services and UI programs that enables marketers to create and deliver end-user personalized offer experiences, across channels and applications using business logic and decision rules. An offer is a marketing message that may have rules associated with it that specify who is eligible to see the offer.

You can create and deliver offers by making a POST request to the Decisions API.

This tutorial requires a working understanding of APIs, specifically with regards to Offer Decisioning. For more information, see the Offer Decisioning API developer guide. This tutorial also requires that you have a unique placement ID and activity ID value available. If you have not acquired these values, see the tutorials for creating a placement and creating an activity.

Discover this feature in video

Accept and Content-Type headers

The following table shows the valid values which comprise the Content-Type and Accept fields in the request header:

Header name Value
Accept application/vnd.adobe.xdm+json; schema="https://ns.adobe.com/experience/offer-management/decision-response;version=1.0"
Content-Type application/vnd.adobe.xdm+json; schema="https://ns.adobe.com/experience/offer-management/decision-request;version=1.0"

API format

POST /{ENDPOINT_PATH}/{CONTAINER_ID}/decisions
Parameter Description Example
{ENDPOINT_PATH} The endpoint path for repository APIs. https://platform.adobe.io/data/core/ode/
{CONTAINER_ID} The container where the activities are located. e0bd8463-0913-4ca1-bd84-6309134ca1f6

Request

curl -X POST \
  'https://platform.adobe.io/data/core/ode/e0bd8463-0913-4ca1-bd84-6309134ca1f6/decisions' \
  -H 'Accept: application/vnd.adobe.xdm+json; schema="https://ns.adobe.com/experience/offer-management/decision-response;version=1.0"' \
  -H 'Content-Type: application/vnd.adobe.xdm+json; schema="https://ns.adobe.com/experience/offer-management/decision-request;version=1.0'
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'
  -d '{
        "xdm:propositionRequests": [
            {
              "xdm:placementId": "xcore:offer-placement:ffed0456",
              "xdm:activityId": "xcore:offer-activity:ffed0123",
              "xdm:itemCount": 2
            },
            {
              "xdm:placementId": "xcore:offer-placement:ffed0012",
              "xdm:activityId": "xcore:offer-activity:fffc0789"
            }
        ],
        "xdm:profiles": [
            {
              "xdm:identityMap": {
                "SWCUSTID": [
                {
                    "xdm:id": "123@abc.com"
                }
                ]
            },
            "xdm:decisionRequestId": "0AA00002-0000-1337-c0de-c0fefec0fefe"
            }
        ],
        "xdm:allowDuplicatePropositions": {
            "xdm:acrossActivities": true,
            "xdm:acrossPlacements": true
        },
        "xdm:mergePolicy": {
            "xdm:id": "5f3ed32f-eaf1-456c-b0f0-7b338c4cb18a"
        },
        "xdm:responseFormat": {
            "xdm:includeContent": true,
            "xdm:includeMetadata": {
            "xdm:activity": [
                "name"
            ],
            "xdm:option": [
                "name"
            ],
            "xdm:placement": [
                "name"
            ]
            }
        }
      }'
Property Description Example
xdm:propositionRequests This object contains the placement and activity identifiers.
xdm:propositionRequests.xdm:placementId The unique placement identifier. "xdm:placementId": "xcore:offer-placement:ffed0456"
xdm:propositionRequests.xdm:activityId The unique activity identifier. "xdm:activityId": "xcore:offer-activity:ffed0123"
xdm:itemCount The number of offers to be returned. The maximum number is 30. "xdm:itemCount": 2
xdm:profiles This object holds information about the profile for which the decision is requested. For an API request this will contain one profile.
xdm:profiles.xdm:identityMap This object holds a set of end user identities based on the namespace integration code of the identity. The identity map can carry more than one identity of each namespace. For more information on namespaces, see the Identity namespace overview. Email: [{"xdm:id": "123@abc.com"}]
xdm:profiles.xdm:decisionRequestId The ID generated by the client that can be used to uniquely identify a profile decision request. This ID is echoed back in the response and does not influence the outcome of the decision. "xdm:decisionRequestId": "0AA00002-0000-1337-c0de-c0fefec0fefe"
xdm:allowDuplicatePropositions This object the control structure of the De-duplication rules. It consists of a series of flags that indicate if the same option can be proposed across a certain dimension. A flag that is set to true means duplicates are allowed and should not be removed across the category indicated by the flag. A flag set to false means that the decision engine should not make the same proposition across the dimension and instead pick the next best option for one of the sub-decisions.
xdm:allowDuplicatePropositions.xdm:acrossActivities If set to true, multiple activities may get assigned the same option. "xdm:acrossActivities": true
xdm:allowDuplicatePropositions.xdm:acrossPlacements If set to true, multiple placements may get assigned the same option. "xdm:acrossPlacements": true
xdm:mergePolicy.xdm:id Identifies the merge policy by which to govern the data returned by profile access service. If one is not specified in the request, Offer Decisioning won’t pass along anything profile access service, else it would pass the id provided by the caller. "xdm:id": "5f3ed32f-eaf1-456c-b0f0-7b338c4cb18a"
xdm:responseFormat A set of flags that formats the response content.
xdm:responseFormat.xdm:includeContent A boolean value that, if set to true, includes content to the response. "xdm:includeContent": true
xdm:responseFormat.xdm:includeMetadata An object that is used to specify what additional metadata is returned. If this property is not included, then xdm:id and repo:etag are returned by default. name
xdm:responseFormat.xdm:activity This flag identifies the specific metadata information returned for xdm:activity. name
xdm:responseFormat.xdm:option This flag identifies the specific metadata information returned for xdm:option. name, characteristics
xdm:responseFormat.xdm:placement This flag identifies the specific metadata information returned for xdm:placement. name, channel, componentType

Response

A successful response returns information on your proposition, including its unique xdm:propositionId.

{
  "xdm:propositionId": "5d0ffb5e-dfc6-4280-99b6-0bf3131cb8b8",
  "xdm:propositions": [
    {
      "xdm:activity": {
        "xdm:id": "xcore:activity:ffed0123",
        "repo:etag": 4
      },
      "xdm:placement": {
        "xdm:id": "xcore:placement:ffed0456",
        "repo:etag": 1
      },
      "xdm:options": [
        {
          "xdm:id": "xcore:personalized-option:ccc0111",
          "repo:etag": 3,
          "@type": "https://ns.adobe.com/experience/decisioning/content-component-html-template",
          "xdm:content": "<html>some html</html>"
        },
        {
          "xdm:id": "xcore:personalized-option:ccc0222",
          "repo:etag": 5,
          "@type": "https://ns.adobe.com/experience/decisioning/content-component-html-template",
          "xdm:content": "<html>hello, world</html>",
          "xdm:score": 45.65
        }
      ]
    },
    {
      "xdm:activity": {
        "xdm:id": "xcore:activity:ffed0123",
        "repo:etag": 4
      },
      "xdm:placement": {
        "xdm:id": "xcore:placement:ffed0789",
        "repo:etag": 2
      },
      "xdm:fallback": {
        "xdm:id": "xcore:fallback:ccc0222",
        "repo:etag": 5,
        "@type": "https://ns.adobe.com/experience/decisioning/content-component-imagelink",
        "dc:format": "image/png",
        "xdm:deliveryURL": "https://cdn.adobe.com/content/1445323-1134331.png",
        "xdm:content": "https://www.adobe.com/index2.html"
      }
    }
  ],
  "ode:createDate": 1566497582038
}
Property Description Example
xdm:propositionId The unique identifier for the proposition entity associated with an XDM DecisionEvent. "xdm:propositionId": "5d0ffb5e-dfc6-4280-99b6-0bf3131cb8b8"
xdm:propositions This object contains a single decision activity proposition. Multiple options can be returned for the activity. If no options are found, then the activity’s fallback offer is returned. Single decision activity propositions always includes either an options property or a fallback property. When present, the options property cannot be empty.
xdm:propositions.xdm:activity This object contains the unique identifier for an offer activity. "xdm:id": "xcore:activity:ffed0123"
xdm:propositions.xdm:placement This object contains the unique identifier for an offer placement. "xdm:id": "xcore:placement:ffed0456"
xdm:propositions.xdm:options This object contains a single option, including its unique identifier. If present, this object cannot be empty. xdm:id": "xcore:personalized-option:ccc0111
xdm:propositions.xdm:options.@type Defines the type of the component. @type acts as the processing contract for the client. When the experience is assembled, the composer will look for the component(s) that have a specific type. https://ns.adobe.com/experience/offer-management/content-component-imagelink
xdm:propositions.xdm:content The format of the response content. Response content can be: text, html block, or image link
xdm:score The score for an option that is computed as a result of a ranking function associated with the option or the activity. This field will be returned by the API if a ranking function is involved in determining the score of an offer during the ranking. "xdm:score": 45.65
xdm:propositions.xdm:fallback This object contains a single fallback offer, including its unique identifier. "xdm:id": "xcore:fallback:ccc0222"
xdm:propositions.xdm:fallback.dc:format The physical or digital manifestation of the resource. Typically, format should include the media-type of the resource. The format may be used to determine the software, hardware or other equipment needed to display or operate the resource. It is recommended to select a value from a controlled vocabulary, for example, the list of Internet Media Types defining computer media formats. "dc:format": "image/png" or "image/jpeg"
xdm:propositions.xdm:fallback.xdm:deliveryURL An optional URL to read the asset from a content delivery network or service endpoint. This URL is used to access the asset publicly from a user agent. https://d37yhxrr0p3l3l.cloudfront.net/0fd0f090-a148-11ea-89e3-f1f2ad52f7e8/urn:aaid:sc:US:a68c86a6-9295-4940-a083-11916b665500/0/40d78a12-f8b6-3f07-8e67-7cb8ae2cc7ec
ode:createDate The time when the decision response message was created. This is represented as epoch time. "ode:createDate": 1566497582038

Tutorial video

The following video is intended to support your understanding of the components of Offer Decisioning.

Next steps

By following this API guide, you have created and delivered offers using the Decisions API. For more information, see the overview on Offer Decisioning.

On this page