Deliver offers using the Decisioning API

Last update: 2025-01-29
  • Created for:
  • Experienced
    Developer

With Decision Management, you can 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 Decisioning API.

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

Required 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"
Authorization Bearer {ACCESS_TOKEN}
x-gw-ims-org-id {IMS_ORG}
x-sandbox-name {SANDBOX_NAME}
x-api-key {API_KEY}
  • All requests that contain a payload (POST,PUT,PATCH) require the content-type header

API request

API format

POST /{ENDPOINT_PATH}/decisions
Parameter Description Example
{ENDPOINT_PATH} The endpoint path for repository APIs. https://platform.adobe.io/data/core/ods

Request

curl -X POST 'https://platform.adobe.io/data/core/ods/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}' \
-H 'x-sandbox-id: {SANDBOX_ID}' \
-H 'x-request-id: e9ac8d7e-3e77-4b38-8726-555ef1737b32-example' \
-d '{
    "xdm:propositionRequests": [
        {
            "xdm:activityId": "dps:offer-activity:15ded04b1786ea27",
            "xdm:placementId": "dps:offer-placement:15d9bc01d35e1238"
        }
    ],
    "xdm:profiles": [
        {
            "xdm:identityMap": {
                "Email": [
                    {
                        "xdm:id": "example@adobe.com",
                        "primary": true
                    }
                ]
            }
        }
    ],
    "xdm:allowDuplicatePropositions": {
        "xdm:acrossActivities": true,
        "xdm:acrossPlacements": true
    },
    "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 decision identifiers.
xdm:propositionRequests.xdm:placementId The unique placement identifier. "xdm:placementId": "dps:offer-placement:ffed0456"
xdm:propositionRequests.xdm:activityId The unique decision identifier. "xdm:activityId": "dps: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 this page. 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-1224-c0de-cjf98Csj43"
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 decisions 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, Decision Management 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": "dps:activity:ffed0123",
        "repo:etag": 4
      },
      "xdm:placement": {
        "xdm:id": "dps:placement:ffed0456",
        "repo:etag": 1
      },
      "xdm:options": [
        {
          "xdm:id": "dps: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": "dps: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": "dps:activity:ffed0123",
        "repo:etag": 4
      },
      "xdm:placement": {
        "xdm:id": "dps:placement:ffed0789",
        "repo:etag": 2
      },
      "xdm:fallback": {
        "xdm:id": "dps: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 proposition. Multiple options can be returned for the decision. If no options are found, then the decision’s fallback offer is returned. Single decision 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 a decision. "xdm:id": "dps:activity:ffed0123"
xdm:propositions.xdm:placement This object contains the unique identifier for an offer placement. "xdm:id": "dps: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": "dps: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 decision. 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": "dps: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

Response codes

The table below lists all codes that can be returned in the response:

Code Description
200 Success. Decision was made for given activities
400 Invalid request parameter. The request cannot be understood by the server due to malformed syntax.
403 Forbidden, insufficient permissions.
422 Unprocessable entity. The request syntax is correct, however, due to semantic errors it is unable to be processed.
429 Too many requests. The user has sent too many requests in a given amount of time.
500 Internal server error. The server encountered an unexpected condition which prevented it from fulfilling the request.
503 Service unavailable due to server overload. The server is currently unable to handle the request due to a temporary overloading.

Next steps

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

Previous page
Next page

On this page