Welcome to the documentation for the Adobe Target Delivery API!

The Adobe Target Delivery API is based on REST. This documentation describes the resources that make up the Adobe Target Delivery API. HTTP methods are utilized to execute operations on those resources.

Through Adobe Target's Delivery API, you can:

• Deliver experiences across web, including SPAs, and mobile channels as well as non-browser based IoT devices such as a connected TV, kiosk, or in-store digital screen.
• Deliver experiences from any server side platform or application that can make HTTP/s calls.
• Deliver consistent and personalized experiences to a user no matter which channel or devices the user has engaged with your business.
• Cache experiences for a user within a session in your server so that multiple API calls can be avoided and as a result achieve better performance.
• Seamlessly integrate with Adobe Experience Cloud products such as Adobe Analytics, Adobe Audience Manager, and the Experience Cloud ID Service from the server side.

Note: You can still access the legacy /v1/mbox and /v2/batchmbox API documentation. However, new features will be developed in the new Delivery API and will not be backported to the legacy APIs.

Read the changelog for the Delivery API.

Adobe Target offers SDKs to interact with the Target Delivery API and help ease the Adobe Target integration with other Experience Cloud solutions such as Adobe Analytics and Adobe Audience Manager by helping you follow best practices in managing sessions and cookies. Therefore, it is highly recommended to leverage a SDK to mask away these complexities and prevent incorrect utilization of the API.

The Node.js SDK is open sourced and maintained within Github, where you can find the documentation and usage instructions.

Read the changelog for the Node.js SDK

The Java SDK is open sourced and maintained within Github, where you can find the documentation and usage instructions.

Read the changelog for the Java SDK

A Target Delivery API call looks like this:

curl -X POST \
  'https://`clientCode`.tt.omtrdc.net/rest/v1/delivery?client=`clientCode`&sessionId=d359234570e04f14e1faeeba02d6ab9914e' \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache' \
  -d '{
      "context": {
        "channel": "web",
        "browser" : {
          "host" : "demo"
        },
        "address" : {
          "url" : "http://demo.dev.tt-demo.com/demo/store/index.html"
        },
        "screen" : {
          "width" : 1200,
          "height": 1400
        }
      },
        "execute": {
        "mboxes" : [
          {
            "name" : "homepage",
            "index" : 1
          }
        ]
      }
    }'

The clientCode can be retrieved from the Target UI by navigating to Setup > Implementation > Edit Settings > Advanced Settings > Client Code.

Before making a Target Delivery API call, there are a few steps to follow in order for a response to contain the relevant experience to show to an end-user:

1. Create a Target Activity (A/B, XT, AP or Recommendations) using the Form-Based Composer or the Visual Experience Composer.
2. Use the Delivery API to get a response for the mboxes used in the Target Activity created in step 2.
3. Present the experience to the visitor!

It's simple as 1, 2, 3!

Postman is an application that makes it easy to fire API calls. This Postman collection contains sample delivery API calls.

We allow customers to manage permissions for their users when using Adobe Target. In order to make a successful Adobe Target Delivery API call, a token with the right permissions must be passed within the API call. In order to learn more about user permissioning and how to retrieve the token visit this documentation.

curl -X POST \
  'https://demo.tt.omtrdc.net/rest/v1/delivery?client=demo&sessionId=d359234570e04f14e1faeeba02d6ab9914e' \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache' \
  -d '{
      "context": {
        "channel": "web",
        "browser" : {
          "host" : "demo"
        },
        "address" : {
          "url" : "http://demo.dev.tt-demo.com/demo/store/index.html"
        },
        "screen" : {
          "width" : 1200,
          "height": 1400
        }
      },
      "property" : {
        "token": "08b62abd-c3e7-dfb2-da93-96b3aa724d81"
      },
        "execute": {
        "mboxes" : [
          {
            "name" : "homepage",
            "index" : 1
          }
        ]
      }
    }'

Once you have the corresponding token, pass the token into property -> token for every API call that is made. If the property -> token is not passed within every API call, you will not get any content back from Adobe Target.

{
    "status": 200,
    "requestId": "07ce783d-58b9-461c-9f4c-6873aeb00c01",
    "client": "demo",
    "id": {
        "tntId": "d359234570e04f14e1faeeba02d6ab9914e.28_7"
    },
    "edgeHost": "mboxedge28.tt.omtrdc.net",
    "execute": {
        "mboxes": [
            {
                "index": 1,
                "name": "homepage"
            }
        ]
    }
}

As you can see above, without passing the property -> token, you will not get any content back. If you expect content from your API call and are not retrieving any from the response, it is most likely because either the property -> token is not provided or it is being passed in without the correct permissions.

There are multiple ways in which a visitor can be identified within Target. Target uses three identifiers:

Field Name	Description
tntId	The tntId is the primary identifier in Target for a user. You can supply this ID or Target will auto-generate it if the request doesn’t contain one.
thirdPartyId	The thirdPartyId is your company’s identifier for the user that you can send with every call. When a user logs in to a company's site, the company typically creates an ID that is tied to the visitor's account, loyalty card, membership number, or other applicable identifiers for that company.
marketingCloudVisitorId	The marketingCloudVisitorId is used to merge and share data between different Adobe solutions. The marketingCloudVisitorId is required for integrations with Adobe Analaytics and Adobe Audience Manager.
customerIds	Along with the Experience Cloud Visitor ID, additional customer IDs and an authenticated status for each visitor can be utilized

The Target ID or tntId can be seen as a device ID. This tntId is generated automatically by Adobe Target if it isn't provided in the request. Thereafter, subsequent requests need to include this tntId in order for the right content to be delivered to a device used by the user.

curl -X POST \
'https://demo.tt.omtrdc.net/rest/v1/delivery?client=demo&sessionId=10abf6304b2714215b1fd39a870f01afc#1555632114' \
-H 'Content-Type: application/json' \
-H 'cache-control: no-cache' \
-d '{
  "context": {
    "channel": "web",
    "browser" : {
      "host" : "demo"
    },
    "address" : {
      "url" : "http://demo.dev.tt-demo.com/demo/store/index.html"
    },
    "screen" : {
      "width" : 1200,
      "height": 1400
    }
  },
    "execute": {
    "mboxes" : [
      {
        "name" : "SummerOffer",
        "index" : 1
      }
    ]
  }
}'

The above example call demonstrates how a tntId does not need to be passed in. In this scenario, Adobe Target will generate a tntId and provide it in the response as seen below:

{
  "status": 200,
  "requestId": "5b586f83-890c-46ae-93a2-610b1caa43ef",
  "client": "demo",
  "id": {
      "tntId": "10abf6304b2714215b1fd39a870f01afc.28_20"
  },
  "edgeHost": "mboxedge28.tt.omtrdc.net",
  ...
}

The generated tntId is 10abf6304b2714215b1fd39a870f01afc.28_20. Please note that this tntId needs to be used when calling Adobe Target Delivery API for the same user across sessions.

The marketingCloudVisitorId is a universal and persistent ID that identifies your visitors across all solutions in the Experience Cloud. When your organization implements the ID service, this ID lets you identify the same site visitor and their data in different Experience Cloud solutions like Adobe Target, Adobe Analytics or Adobe Audience Manager. Please note that the marketingCloudVisitorId is required when leveraging and integrating with Analytics and Audience Manager.

curl -X POST \
  'https://demo.tt.omtrdc.net/rest/v1/delivery?client=demo&sessionId=10abf6304b2714215b1fd39a870f01afc#1555632114' \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache' \
  -d '{
  "id": {
    "marketingCloudVisitorId": "10527837386392355901041112038610706884"
  },
  "context": {
    "channel": "web",
    "browser" : {
      "host" : "demo"
    },
    "address" : {
      "url" : "http://demo.dev.tt-demo.com/demo/store/index.html"
    },
    "screen" : {
      "width" : 1200,
      "height": 1400
    }
  },
    "execute": {
    "mboxes" : [
      {
        "name" : "SummerOffer",
        "index" : 1
      }
    ]
  }
}'

The above example call demonstrates how a marketingCloudVisitorId that was retrieved from the Experience Cloud ID Service is passed to Adobe Target. In this scenario, Adobe Target will generate a tntId since it was not passed into the original call which will be mapped to the provided marketingCloudVisitorId as seen below in the response.

{
    "status": 200,
    "requestId": "80173866-9026-4ac7-b467-a0ba178a591b",
    "client": "demo",
    "id": {
        "tntId": "10abf6304b2714215b1fd39a870f01afc.28_20",
        "marketingCloudVisitorId": "10527837386392355901041112038610706884"
    },
    "edgeHost": "mboxedge28.tt.omtrdc.net",
    ...
}

If your organization uses an ID to identify your visitor, you can use thirdPartyID to deliver content. However, you must provide the thirdPartyID for every Adobe Target Delivery API call you make.

curl -X POST \
  'https://demo.tt.omtrdc.net/rest/v1/delivery?client=demo&sessionId=10abf6304b2714215b1fd39a870f01afc#1555632114' \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache' \
  -d '{
  "id": {
    "thirdPartyId": "B234A029348"
  },
  "context": {
    "channel": "web",
    "browser" : {
      "host" : "demo"
    },
    "address" : {
      "url" : "http://demo.dev.tt-demo.com/demo/store/index.html"
    },
    "screen" : {
      "width" : 1200,
      "height": 1400
    }
  },
    "execute": {
    "mboxes" : [
      {
        "name" : "SummerOffer",
        "index" : 1
      }
    ]
  }
}'

The above example call demonstrates how a thirdPartyId, which is a persistent ID that your business utilizes to identify an end-user regardless of whether they are interacting with your business from web, mobile, or IoT channels. In other words, the thirdPartyId will reference user profile data that can be utilized across channels. In this scenario, Adobe Target will generate a tntId since it was not passed into the original call which will be mapped to the provided thirdPartyId as seen below in the response.

{
    "status": 200,
    "requestId": "55de9886-bd14-4dee-819c-7d1633b79b90",
    "client": "demo",
    "id": {
        "tntId": "10abf6304b2714215b1fd39a870f01afc.28_20",
        "thirdPartyId": "B234A029348"
    },
    "edgeHost": "mboxedge28.tt.omtrdc.net",
    ...
}

Customer IDs can be added and associated with an Experience Cloud Visitor ID. Whenever sending customerIds the marketingCloudVisitorId must also be provided. Furthermore, an authentication status can be provided along with each customerId for each visitor. The following authentication status can be taken into consideration:

Authentication Status	User Status
unknown	Unknown or never authenticated. This state can be used for scenarios like a visitor that has landed on your site by clicking on a display advert.
authenticated	The user is currently authenticated with an active session on your website or app.
logged_out	The user was authenticated but actively logged out. The user intended and meant to disconnect from the authenticated state. The user no longer wants to be treated as authenticated.

Please note that only when the customer id is in authenticated state will Target reference the user profile data that is stored and linked to the customer id. If the customer id is in unknown or logged_out state, then the customer id will be ignored and any user profile data that may be associated with it will not be leveraged for audience targeting.

curl -X POST \
  'https://demo.tt.omtrdc.net/rest/v1/delivery?client=demo&sessionId=d359234570e044f14e1faeeba02d6ab23439914e' \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache' \
  -d '{
      "context": {
        "channel": "web",
        "browser" : {
          "host" : "demo"
        },
        "address" : {
          "url" : "http://demo.dev.tt-demo.com/demo/store/index.html"
        },
        "screen" : {
          "width" : 1200,
          "height": 1400
        }
      },
      "id": {
        "marketingCloudVisitorId" : "2304820394812039",
        "customerIds": [{
          "id": "134325423",
          "integrationCode" : "crm_data",
          "authenticatedState" : "authenticated"
        }]
      },
      "property" : {
        "token": "08b62abd-c3e7-dfb2-da93-96b3aa724d81"
      },
        "execute": {
        "mboxes" : [
          {
            "name" : "homepage",
            "index" : 1
          }
        ]
      }
    }'

The above example call demonstrates how to send a customerId with an authenticatedState. When sending a customerId, the integrationCode, id, and authenticatedState as well as the marketingCloudVisitorId are required. The integrationCode is the alias of the customer attributes file you provided through CRS.

You can combine tntId, thirdPartyID, and marketingCloudVisitorId in the same request. In this scenario, Adobe Target will maintain the mapping of all these IDs and pin it to a visitor. Learn how profiles are merged and synced in real time using the different identifiers.

curl -X POST \
  'https://demo.tt.omtrdc.net/rest/v1/delivery?client=demo&sessionId=d359234570e044f14e1faeeba02d6ab23439914e' \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache' \
  -d '{
      "context": {
        "channel": "web",
        "browser" : {
          "host" : "demo"
        },
        "address" : {
          "url" : "http://demo.dev.tt-demo.com/demo/store/index.html"
        },
        "screen" : {
          "width" : 1200,
          "height": 1400
        }
      },
      "id": {
        "marketingCloudVisitorId" : "2304820394812039",
        "tntId": "d359234570e044f14e1faeeba02d6ab23439914e.28_78",
        "thirdPartyId":"23423432"
      },
      "property" : {
        "token": "08b62abd-c3e7-dfb2-da93-96b3aa724d81"
      },
      "experienceCloud": {
        "analytics": {
          "supplementalDataId" : "23423498732598234",
          "trackingServer": "ags041.sc.omtrdc.net",
          "logging": "server_side"
        }
      },
        "execute": {
        "mboxes" : [
          {
            "name" : "homepage",
            "index" : 1
          }
        ]
      }
    }'

The above example call demonstrates how you can combine tntId, thirdPartyID, and marketingCloudVisitorId in the same request. All 3 IDs are also returned in the response as well.

{
    "status": 200,
    "requestId": "8e352d0d-103e-44ba-bdf4-bb7319dc3747",
    "client": "demo",
    "id": {
        "tntId": "d359234570e044f14e1faeeba02d6ab23439914e.28_78",
        "thirdPartyId": "23423432",
        "marketingCloudVisitorId": "2304820394812039"
    ...
}

The Adobe Target Delivery API supports a single or batch delivery call. One can make a server request for content for single or multiple mboxes. Please make sure to outweigh the performance costs when making a single call vs a batched call. If you know all of the content that needs to be shown for a user, it is best practice to retrieve content for all mboxes with a single batch delivery call so that you avoid making multiple single delivery calls.

You can retrieve an experience to display to the user for one mbox via the Adobe Target Delivery API. Note that if you are making a single delivery call, you would need to initiate another server call to retrieve additional content for an mbox for a user. This can become very costly over time, so please make sure to evaluate your approach when using the single delivery API call.

curl -X POST \
'https://demo.tt.omtrdc.net/rest/v1/delivery?client=demo&sessionId=7abf6304b2714215b1fd39a870f01afc#1555632114' \
-H 'Content-Type: application/json' \
-H 'cache-control: no-cache' \
-d '
{
  "id": {
    "tntId": "abcdefghijkl00023.1_1"
  },
  "context": {
    "channel": "web",
    "browser" : {
      "host" : "demo"
    },
    "address" : {
      "url" : "http://demo.dev.tt-demo.com/demo/store/index.html"
    },
    "screen" : {
      "width" : 1200,
      "height": 1400
    }
  },
    "execute": {
    "mboxes" : [
      {
        "name" : "SummerOffer",
        "index" : 1
      }
    ]
  }
}'

In the single delivery call example above, we are retrieving the experience to display for the user with tntId: abcdefghijkl00023.1_1 for an mbox:SummerOffer on the web channel. This single delivery call will generate the following response:

{
  "status": 200,
  "requestId": "25e0cc42-3d7b-456a-8b49-af60c1fb23d9",
  "client": "demo",
  "id": {
      "tntId": "abcdefghijkl00023.1_1"
  },
  "edgeHost": "mboxedge28.tt.omtrdc.net",
  "execute": {
      "mboxes": [
          {
              "index": 1,
              "name": "SummerOffer",
              "options": [
                  {
                      "content": "<p><b>Enjoy this 15% discount on your next purchase</b></p>",
                      "type": "html",
                  }
              ]
          }
      ]
    }
}

In the response, you can see that the content field contains the HTML that describes the experience to be shown to the user for the web that corresponds to the SummerOffer mbox.

Execute Page Load

If there are experiences that should be shown when a page load happens in the web channel such as AB testing the fonts located in the footer or header, you can specify pageLoad in the execute field to retrieve all modifications that should be applied.

curl -X POST \
  'https://demo.tt.omtrdc.net/rest/v1/delivery?client=demo&sessionId=d359570e04f14e1faeeba02d6ab9914e' \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache' \
  -d '{
  "id": {
    "tntId": "84e8d0e211054f18af365d65f45e902b.28_131"
  },
  "context": {
    "channel": "web",
    "window": {
      "width": 1819,
      "height": 842
    },
    "browser": {
      "host": "target.enablementadobe.com"
    },
    "address": {
      "url": "https://target.enablementadobe.com/react/demo/#/"
    }
  },
  "execute": {
    "pageLoad": {}
  }
}'

The above sample call is to retrieve any experiences to show to a user when the page https://target.enablementadobe.com/react/demo/#/ loads.

{
      "status": 200,
      "requestId": "355ebc47-edb6-481f-aeae-ae55d71afaca",
      "client": "demo",
      "id": {
          "tntId": "84e8d0e211054f18af365d65f45e902b.28_131"
      },
      "edgeHost": "mboxedge28.tt.omtrdc.net",
      "execute": {
          "pageLoad": {
              "options": [
                  {
                      "content": [
                          {
                              "type": "setHtml",
                              "selector": "#app > DIV:nth-of-type(1) > DIV:nth-of-type(1) > NAV.nav:eq(0) > DIV.container:eq(0) > DIV.nav-right:eq(0) > A.nav-item:eq(0)",
                              "cssSelector": "#app > DIV:nth-of-type(1) > DIV:nth-of-type(1) > NAV:nth-of-type(1) > DIV:nth-of-type(1) > DIV:nth-of-type(2) > A:nth-of-type(1)",
                              "content": "Modified Home"
                          }
                      ],
                      "type": "actions"
                  }
              ],
              "metrics": [
                  {
                      "type": "click",
                      "selector": "#app > DIV:nth-of-type(1) > DIV:nth-of-type(2) > SECTION.section:eq(0) > DIV.container:eq(0) > FORM.col-md-4:eq(0) > DIV.form-group:eq(0) > BUTTON.btn:eq(0)",
                      "eventToken": "QPaLjCeI9qKCBUylkRQKBg=="
                  }
              ]
          }
      }
  }

In the content field the modification that needs to be applied on a page load can be retrieved. In the example above, you can see that a link on the header needs to be named to Modified Home.

Instead of making multiple delivery calls with a single mbox in each call, making one delivery call with a batch of mboxes can reduce unnecessary server calls. Invoking a server call should be minimized as much as possible in order to be highly performant.

curl -X POST \
'https://demo.tt.omtrdc.net/rest/v1/delivery?client=demo&sessionId=7abf6304b2714215b1fd39a870f01afc#1555632114' \
-H 'Content-Type: application/json' \
-H 'cache-control: no-cache' \
-d '
{
  "id": {
    "tntId": "abcdefghijkl00023.1_1"
  },
  "context": {
    "channel": "web",
    "browser" : {
      "host" : "demo"
    },
    "address" : {
      "url" : "http://demo.dev.tt-demo.com/demo/store/index.html"
    },
    "screen" : {
      "width" : 1200,
      "height": 1400
    }
  },
    "execute": {
    "mboxes" : [
      {
        "name" : "SummerOffer",
        "index" : 1
      },
      {
        "name" : "SummerShoesOffer",
        "index" : 2
      },
      {
        "name" : "SummerDressOffer",
        "index" : 3
      }      
    ]
  }
}'

In the batched delivery call example above, we are retrieving the experiences to display for the user with tntId: abcdefghijkl00023.1_1 for multiple mbox:SummerOffer, SummerShoesOffer, and SummerDressOffer. Since we know that we need to show an experience for multiple mboxes for this user, we can batch these requests and make 1 server call instead of 3 individual delivery calls.

{
  "status": 200,
  "requestId": "fe15286f-effb-434f-85d8-c3db804075ce",
  "client": "demo",
  "id": {
      "tntId": "abcdefghijkl00023.28_120"
  },
  "edgeHost": "mboxedge28.tt.omtrdc.net",
  "execute": {
      "mboxes": [
          {
              "index": 1,
              "name": "SummerOffer",
              "options": [
                  {
                      "content": "<p><b>Enjoy this 15% discount on your next purchase</b></p>",
                      "type": "html",

                  }
              ]
          },
          {
              "index": 2,
              "name": "SummerShoesOffer",
              "options": [
                  {
                      "content": "<p><b>Enjoy this 15% discount on your next shoe purchase</b></p>",
                      "type": "html",
                  }
              ]
          },
          {
              "index": 3,
              "name": "SummerDressOffer",
              "options": [
                  {
                      "content": "<p><b>Enjoy this 15% discount on your next dress purchase</b></p>",
                      "type": "html",
                  }
              ]
          }
      ]
  }
}

In the response above, you can see that within the content field of each mbox, the HTML representation of the experience to show to the user for each mbox is retrievable.

Prefetching allows clients like mobile apps and servers to fetch content for multiple mboxes or views in one request, cache it locally, and later notify Target when the user visits those mboxes or views. When utilizing prefetch, it's important to be familiar with the following terms:

Field Name	Description
prefetch	List of mboxes and views that should be fetched but shouldn’t be marked as visited. The Target Edge returns an eventToken for each mbox or view that exist in the prefetch array
notifications	List of mboxes and views that were previously prefetched and should be marked as visited.
eventToken	A hashed encrypted token that is returned when content is prefetched. This token should be sent back to Target in the notifications array.

Clients like mobile apps and servers can prefetch multiple mboxes for a given user within a session and cache it in order to avoid multiple calls to Adobe Target Delivery API.

curl -X POST \
'https://demo.tt.omtrdc.net/rest/v1/delivery?client=demo&sessionId=7abf6304b2714215b1fd39a870f01afc#1555632114' \
-H 'Content-Type: application/json' \
-H 'cache-control: no-cache' \
-d