Introduction
You can use Adobe Target’s Admin and Profile REST APIs that use the Adobe.IO integration to manage activities, audiences, offers, properties, reports, mboxes, environments, and profiles.
Adobe.IO Integration
Sample request to exchange a JWT token with a Bearer Access Token
curl -X POST \
'https://ims-na1.adobelogin.com/ims/exchange/jwt/?client_id=<Adobe.IO API KEY>&client_secret=<Adobe.IO Client Secret>&jwt_token=JWT_TOKEN'
Sample response with the Bearer Access Token
{
"token_type": "bearer",
"access_token": "eyJ4NXUiOiJpbXNfbmExLWtleS0xLmNlciIsImFsZyI6IlJTMjU2In0.eyJpZCI6IjE1MzM2NjIxNDAzNTNfOWFiYWRlNTYtZWY5YS00ZmM0LTg2MjYtZTMyYjk2Y2JjMTM0X3VlMSIsImNsaWVudF9pZCI6ImE5YjQ0YWQzZjgxMzQyNTg5NDRkNmVkYmE1MGZjNTFkIiwidXNlcl9pZCI6IjY2OUM3RkQ3NUFDM0UxNTgwQTQ5NUU3MEB0ZWNoYWNjdC5hZG9iZS5jb20iLCJ0eXBlIjoiYWNjZXNzX3Rva2VuIiwiYXMiOiJpbXMtbmExIiwiZmciOiJTVkRLWDZSNEZMTjdDSERPQUVBQUFBQUFWQT09PT09PSIsInNpZCI6IjE1MzM2NjIxNDAzNTVfOTE0NWIyMDItZjg3OC00ZjBiLWFhYjMtNmVkZTUzZWRkOTgyX3VlMSIsIm1vaSI6IjI1MGQ4MzFmIiwiYyI6ImJEMFJlQUQ0bU5sRzV4Z0psTmFJQmc9PSIsImV4cGlyZXNfaW4iOiI4NjQwMDAwMCIsInNjb3BlIjoib3BlbmlkLEFkb2JlSUQsdGFyZ2V0X3NkayxyZWFkX29yZ2FuaXphdGlvbnMsYWRkaXRpb25hbF9pbmZvLnByb2plY3RlZFByb2R1Y3RDb250ZXh0IiwiY3JlYXRlZF9hdCI6IjE1MzM2NjIxNDAzNTMifQ.AXpmjYPFUxvSkKjkO9DryCbqeGQDlrR07HIHjY-9alQIxe0JNIRfOjRjginvOO6ihWA71lfvtJ5iD6Yc7L9EDCCnztjSYYKfvK8NlDyN7uTOT7-Ky7OFQPnFX7m57d3vblj0Daq9Xbo0MbDfUtBl-0RpsfMz3tBN5OP1tOkgweuGHmnmeg-mUhbZf0SVrvlfM1aXQMx2gAL4c12f1YfviSUPQUPzB3ZozNHxKf321HiG-bUW06tRdZRdH-KhupdsJUlAHXSBZNDp0Gn93uGoDxNO7xuOqcFhRAJuqJQ96njPKLzmD_6V0SDDGHYb1IEcx7n0OYIf4BMK46W9tYXbdQ",
"expires_in": 86399990
}
All Admin APIs and the Authenticated Profile APIs must use the Adobe.IO integration. You can create an Adobe.io integration by following these steps:
- Login to https://console.adobe.io and create a Target Integration by following the instructions here.
- Note that you must be a product admin to create an integration.
- Generate a JSON Web Token (JWT) as described in the Adobe.io documentation.
- Exchange the JWT for a Bearer Access Token by using the request shown in the example alongside. The Access Token has an expiry value set and must be re-created on expiry.
- All Adobe.IO APIs must include the Access Token in the request header.
Authentication Tokens
Generate a Debug Authentication Token for use with mboxTrace
curl -X POST \
'https://mc.adobe.io/<your-tenant-name>/target/authentication/token?scope=debug_tools' \
-H 'Authorization: Bearer BEARER_TOKEN_FROM_JWT_EXCHANGE' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/vnd.adobe.target.v1+json' \
-H 'X-Api-Key: a9b44ad3f8134258944d6edba50fc51d'
Generate a Profile Authentication Token for use with Profile APIs
curl -X POST \
'https://mc.adobe.io/<your-tenant-name>/target/authentication/token?scope=profile_api' \
-H 'Authorization: Bearer BEARER_TOKEN_FROM_JWT_EXCHAGE' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/vnd.adobe.target.v1+json' \
-H 'X-Api-Key: a9b44ad3f8134258944d6edba50fc51d'
Response to the Profile Authentication Token request
{
"accessToken": "bbf8ae69-6e29-4b8e-b3d6-f7567723f5b0",
"tokenType": "bearer",
"scope": "profile_api",
"expiresIn": 7775999
}
For accessing authenticated Profile APIs, you can generate the Authentication Tokens using the Adobe.IO Authentication Token API.
https://mc.adobe.io/<your-tenant-name>/target/authentication/token?scope=<AUTHENTICATION_SCOPE>
Profile Authentication Token
The profile authentication token helps work with the Profile API that has Authenticated switched ON. This can be generated by setting scope=profile_api in the API request as shown in Example 2. The response returns the accessToken which should be passed in the profile API request headers as
-H 'access_token: VALUE_OF_ACCESS_TOKEN'.
Admin APIs
The Admin APIs will allow you to CRUD (Create, Read, Update and Delete) Activities, Audiences and Offers.
Before you Begin
In all the code examples, you must replace the {tenant} variable with your tenant value, your-bearer-token with the access token that you generate with your JWT and your-api-key with your API key from the Adobe I/O console.
Versioning
Error Message for unsupported features
{
"httpStatus": 406,
"requestId": "8752b736-cf71-4d81-86c3-94be2b5ae648",
"requestTime": "2018-02-02T21:39:06.405Z",
"errors": [
{
"errorCode": "Unsupported.Feature",
"message": "Unsupported features detected"
}
]
}
All APIs have a version associated with it. It is important to provide the right version of the API that you want to use.
If the request contains a payload (POST or PUT), the Content-Type header of the request is used to specify the version.
If the request doesn’t contain a payload (GET, DELETE or OPTIONS), the Accept header is used to specify the version.
If a version isn’t provided, the call will default to V1 (application/vnd.adobe.target.v1+json) .
Admin Postman Collection
Postman is a application that makes it easy to fire API calls. This Postman collection contains all the Admin API calls in the same order as the docs. Just click on the ‘Run in Postman’ button to import the Target API collection.
This collection contains all APIs that require authentication using Adobe I/O * Activities * Audiences * Offers * Reports * Mboxes and Environments
Response Codes
Here are the common response codes for the Target Admin APIs
| Status | Meaning | Description |
|---|---|---|
| 200 | OK | OK |
| 400 | Bad Request | Bad Request. Most probably the data provided in the request is invalid. |
| 401 | Unauthorized | The user is not allowed to perform this operation. |
| 403 | Forbidden | Access to this resource is forbidden. |
| 404 | Not Found | The referenced resource was not found. |
Activities
An activity enables you to test, target or personalize content for your users. An activity can be one of the following types
- AB Test
- Experience Targeting
- Recommendations
- Automated Personalization
- Multi-Variate Test
List Activities
Sample Request for GET Activities
curl -X GET
https://mc.adobe.io/<your-tenant-name>/target/activities/ \
-H 'authorization: Bearer <your-bearer-token>' \
-H 'cache-control: no-cache' \
-H 'Accept: application/vnd.adobe.target.v3+json' \
-H 'x-api-key: <your-api-token>'
Sample Response for GET Activities
{
"total": 5,
"offset": 0,
"limit": 2147483647,
"activities": [
{
"id": 168805,
"thirdPartyId": "2fc846c4-d5c6-4d67-9ef8-939bb907cc71",
"type": "ab",
"state": "deactivated",
"name": "A3 - L4242 - Serversid testing",
"priority": 0,
"modifiedAt": "2017-05-11T10:11:35Z",
"workspace": "1234567"
},
{
"id": 168942,
"thirdPartyId": "e1cfda1a-5814-4dd9-8624-c33882af114b",
"type": "xt",
"state": "deactivated",
"name": "A3-L4242-XT",
"priority": 0,
"modifiedAt": "2017-05-11T10:11:52Z",
"workspace": "1234567"
},
{
"id": 168816,
"thirdPartyId": "f7134ab6-ee98-422f-a59d-a1efc3cd85a9",
"type": "ab",
"state": "deactivated",
"name": "A5-L4242",
"priority": 0,
"modifiedAt": "2017-05-11T10:11:33Z",
"workspace": "1234567"
},
{
"id": 168824,
"thirdPartyId": "60a2f81f-e2bb-45be-9e9a-90162cfcf780",
"type": "ab",
"state": "deactivated",
"name": "A6-L4242 AB Test SG",
"priority": 0,
"modifiedAt": "2017-05-11T10:11:18Z",
"workspace": "1234567"
}
]
}
Get a list of activities created in your Target account, with the ability to filter and sort by attributes.
GET: /{tenant}/target/activities
Parameters
| Parameter | Required | Description | Example |
|---|---|---|---|
| limit | False | Defines the number of items to return. Default value is 2147483647 | Returns the first ten items ?limit=10 |
| offset | False | Defines the first activity to return from the list of total activities. Used in conjunction with limit, you can provide pagination in your application for users to browse through a large set of activities. | Return the first ten items with an offset ?limit=10&offset=0 ?limit=10&offset=10 |
| sortBy | False | Defines the sorting criteria on the returned items. You can sort by:
|
Sort Activities ?sortBy=id&limit=10/?sortBy=-id&limit=10 /?sortBy=id&sortBy=-name&limit=10 |
Some common Examples
GET list of all activities
https://mc.adobe.io/{tenant}/target/activities/
GET activity list with limit
https://mc.adobe.io/{tenant}/target/activities/?limit=1
GET activity list with limit and offset
https://mc.adobe.io/{tenant}/target/activities/?limit=2&offset=2
GET activity list filtered by multiple values
https://mc.adobe.io/{tenant}/target/activities/?id=3&id=4&name=ab
GET activity list filtered by negative values
https://mc.adobe.io/{tenant}/target/activities/?priority=!4
GET activity list sorted by multiple criteria
https://mc.adobe.io/{tenant}/target/activities/?sortBy=name&sortBy=id
GET activity list filtered by a date range
https://mc.adobe.io/{tenant}/target/activities/?startsAt=1800-09-01T02:04:00.000-07:00/2114-11-30T14:10:00.000-07:00
GET activity list filtered by workspaces
https://mc.adobe.io/{tenant}/target/activities/?workspace=1234567,12345678
Get AB Activity by ID
Sample Request for Get AB Activity by ID
curl -X GET
https://mc.adobe.io/<your-tenant-name>/target/activities/ab/168824 \
-H 'authorization: Bearer <your-bearer-token>' \
-H 'cache-control: no-cache' \
-H 'Accept: application/vnd.adobe.target.v3+json' \
-H 'x-api-key: <your-api-token>'
Sample Response for Get AB Activity by ID
{
"id": 168824,
"thirdPartyId": "60a2f81f-e2bb-45be-9e9a-90162cfcf780",
"name": "A6-L4242 AB Test SG",
"state": "deactivated",
"priority": 0,
"autoAllocateTraffic": {
"enabled": false,
"successEvaluationCriteria": "conversion_rate"
},
"locations": {
"mboxes": [
{
"locationLocalId": 0,
"name": "a6-serverside-ab"
}
]
},
"experiences": [
{
"experienceLocalId": 0,
"name": "Experience A",
"visitorPercentage": 34,
"offerLocations": [
{
"locationLocalId": 0,
"offerId": 395818
}
]
},
{
"experienceLocalId": 1,
"name": "Experience B",
"visitorPercentage": 33,
"offerLocations": [
{
"locationLocalId": 0,
"offerId": 395819
}
]
},
{
"experienceLocalId": 2,
"name": "Experience C",
"visitorPercentage": 33,
"offerLocations": [
{
"locationLocalId": 0,
"offerId": 395820
}
]
}
],
"metrics": [
{
"metricLocalId": 32767,
"name": "MY PRIMARY GOAL",
"conversion": true,
"mboxes": [
{
"name": "order-complete",
"successEvent": "mbox_shown"
}
],
"action": {
"type": "count_once"
}
}
],
"workspace": "1234567",
"propertyIds": [
1,
2
],
"modifiedAt": "2017-05-11T10:11:18Z"
}
Fetch the current definition of an AB activity if it is found as referenced by the id.
GET /{tenant}/target/activities/ab/{id}
Delete AB activity by ID
Sample Request for Delete AB Activity by ID
curl -X DELETE \
https://mc.adobe.io/<your-tenant-name>/target/activities/ab/168805 \
-H 'authorization: Bearer <your-bearer-token>' \
-H 'cache-control: no-cache' \
-H 'Accept: application/vnd.adobe.target.v3+json' \
-H 'x-api-key: <your-api-token>'
Sample Response for Delete XT Activity by ID
{
"id": 168805,
"thirdPartyId": "2fc846c4-d5c6-4d67-9ef8-939bb907cc71_1499636562807",
"name": "A3 - L4242 - Serversid testing",
"state": "deleted",
"priority": 0,
"autoAllocateTraffic": {
"enabled": false,
"successEvaluationCriteria": "conversion_rate"
},
"locations": {
"mboxes": [
{
"locationLocalId": 0,
"name": "a3-serverside-ab"
}
]
},
"experiences": [
{
"experienceLocalId": 0,
"name": "Experience A",
"visitorPercentage": 34,
"offerLocations": [
{
"locationLocalId": 0,
"offerId": 395818
}
]
},
{
"experienceLocalId": 1,
"name": "Experience B",
"visitorPercentage": 33,
"offerLocations": [
{
"locationLocalId": 0,
"offerId": 395819
}
]
},
{
"experienceLocalId": 2,
"name": "Experience C",
"visitorPercentage": 33,
"offerLocations": [
{
"locationLocalId": 0,
"offerId": 395820
}
]
}
],
"metrics": [
{
"metricLocalId": 32767,
"name": "MY PRIMARY GOAL",
"conversion": true,
"action": {
"type": "count_once"
}
}
],
"workspace": "1234567",
"propertyIds": [
1,
2
],
"modifiedAt": "2017-07-09T21:42:42Z"
}
Deletes the AB activity that is referenced by the id, if it is found.
DELETE: /{tenant}/target/activities/ab/{id}
Create AB Activity
Sample Request for Create AB Activity
curl -X POST \
https://mc.adobe.io/<your-tenant-name>/target/activities/ab/ \
-H 'authorization: Bearer <your-bearer-token>' \
-H 'cache-control: no-cache' \
-H 'content-type: application/vnd.adobe.target.v3+json' \
-H 'x-api-key: <your-api-token>'
-d '{
"name": "New API Activity",
"startsAt": "2017-05-01T08:00Z",
"endsAt": "2017-09-01T07:59:59Z",
"state": "saved",
"priority": 100,
"autoAllocateTraffic": {
"enabled": false,
"successEvaluationCriteria": "conversion_rate"
},
"locations": {
"mboxes": [
{
"locationLocalId": 0,
"name": "x1-serverside-ab"
}
]
},
"experiences": [
{
"experienceLocalId": 0,
"name": "Experience A",
"visitorPercentage": 34,
"offerLocations": [
{
"locationLocalId": 0,
"offerId": 395818
}
]
},
{
"experienceLocalId": 1,
"name": "Experience B",
"visitorPercentage": 33,
"offerLocations": [
{
"locationLocalId": 0,
"offerId": 395819
}
]
},
{
"experienceLocalId": 2,
"name": "Experience C",
"visitorPercentage": 33,
"offerLocations": [
{
"locationLocalId": 0,
"offerId": 395820
}
]
}
],
"metrics": [
{
"metricLocalId": 32767,
"name": "MY PRIMARY GOAL",
"conversion": true,
"mboxes": [
{
"name": "order-complete",
"successEvent": "mbox_shown"
}
],
"action": {
"type": "count_once"
}
}
],
"workspace": "1234567",
"propertyIds": [
1,
2
]
}'
Sample Response for Create AB Activity
{
"id": 183916,
"name": "New API Activity",
"startsAt": "2017-05-01T08:00Z",
"endsAt": "2017-09-01T07:59:59Z",
"state": "saved",
"priority": 100,
"autoAllocateTraffic": {
"enabled": false,
"successEvaluationCriteria": "conversion_rate"
},
"locations": {
"mboxes": [
{
"locationLocalId": 0,
"name": "x1-serverside-ab"
}
]
},
"experiences": [
{
"experienceLocalId": 0,
"name": "Experience A",
"visitorPercentage": 34,
"offerLocations": [
{
"locationLocalId": 0,
"offerId": 395818
}
]
},
{
"experienceLocalId": 1,
"name": "Experience B",
"visitorPercentage": 33,
"offerLocations": [
{
"locationLocalId": 0,
"offerId": 395819
}
]
},
{
"experienceLocalId": 2,
"name": "Experience C",
"visitorPercentage": 33,
"offerLocations": [
{
"locationLocalId": 0,
"offerId": 395820
}
]
}
],
"metrics": [
{
"metricLocalId": 32767,
"name": "MY PRIMARY GOAL",
"conversion": true,
"mboxes": [
{
"name": "order-complete",
"successEvent": "mbox_shown"
}
],
"action": {
"type": "count_once"
}
}
],
"workspace": "1234567",
"propertyIds": [
1,
2
],
"modifiedAt": "2017-07-10T05:11:03Z"
}
POST /{tenant}/target/activities/ab
Creates a new AB activity with the specified contents and returns the created activity.
Parameters
| Attribute | Type | Description |
|---|---|---|
| id | Number | A unique value generated by the server when the activity is created. Subsequently, it is used to identify an activity. |
| thirdPartyId | String | An alternative id to identify an activity, usually generated by the client. If specified, must be unique amongst all activities. Max length is 250 characters. |
| name | String | A string to identify the activity. The name cannot be empty. Max length is 250 characters. |
| startsAt | String | The date and time to start an activity. Supports ISO 8601 style date-hour formats. |
| endsAt | String | The date and time to end an activity. Supports ISO 8601 style date-hour formats. |
| state | String |
Defines the state of the activity. Possible values are:
|
| priority | String | Defines the priority of the activity. Higher numbers have higher priority.Valid values are between 0 and 999. Default value is 5. |
| entryConstraint | String | Specifies an activity entry constraint via an mbox-audience combination or visitor percentage. Specifies the mbox, audienceId, and visitor percentage required to enter the activity. |
| experiences | Array | A list of locations on the page where the content offer is served. A location contains the following:
|
| workspace | String | Optional id of workspace to which the activity belongs. Max length is 250 characters. By default, Default workspace is assumed. Applicable for Enterprise Permissions (Target Premium). |
| propertyIds | Array | List of property ids to associate with the activity. |
| locations | Array | A list of locations on the page where the content offer is served. |
| locations > mboxes | Array |
a list of mboxes to serve the offers in. |
| locations > mboxes > locationLocalId | String |
Used to track the location during PUT/POST requests |
| locations > mboxes > name | String | The name of the mbox. |
| locations > mboxes > audienceId | Array | A list of audienceIds to target on the mbox |
| metrics | Array | List of metrics to collect for the activity. |
| metrics > metricLocalId | String | Used to track the metric across POST/PUT requests. |
| metrics > name | Array | Used to identify the metric |
| metrics > conversion | Boolean | Used to indicate if the metric is a conversion metric |
| metrics > action | JSON |
Used to specify the action to take when the metric number is increased |
| metrics > action > type | Enum |
Type of action. The valid values are:
|
| metrics > action > conditions | additional conditions applicable for ban_from_campaign and experience_frequency_capping | |
| metrics > action > conditions > maxVisitCount | Number | |
| metrics > action > conditions > maxImpressionCount | Number | |
| metrics > action > conditions > experiences | Used for details of the experiences | |
| metrics > action > conditions > experiences | Used for details of the experiences | |
| metrics > action > conditions > experiences > experienceLocalId | to track the experience across POST/PUT requests | |
| metrics > action > conditions > experiences > maxVisitCount | ||
| metrics > action > conditions > experiences > maxImpressionCount | ||
| metrics > action > onConditionMetAction |
Used to specify the action to take when the condition is met. Valid values are restart_new_experience or restart_random_experience. This value is only applicable if action > type=experience_frequence_capping. |
|
| metrics > action > mboxes | An optional list of mboxes for which metrics should be collected | |
| metrics > action > mboxes > name | String | a text identifier for the mbox |
| metrics > action > mboxes > successEvent | String | Used to specify the success metric event. Valid values are: mbox_shown, or mbox_clicked. |
| metrics > action > mboxes > audienceId | String | optional audienceId to only track specific cases. |
| reportingAudiences | Segments used for reporting | |
| reportingAudiences > reportingAudienceLocalId | Used to track metrics across POST/PUT requests | |
| reportingAudiences > audienceId | Segments used for reporting | |
| reportingAudiences > metricLocalId | ||
| analytics | Used to configure integration with Adobe Analytics | |
| analytics > reportSuite | Report suite configuration for Adobe Analytics | |
| analytics > dataCollectionHost | Used to denote data collection host for Adobe Analytics |
Update AB Activity
Sample Request for Update AB Activity
curl -X PUT \
https://mc.adobe.io/<your-tenant-name>/target/activities/ab/183916 \
-H 'authorization: Bearer <your-bearer-token>' \
-H 'cache-control: no-cache' \
-H 'content-type: application/vnd.adobe.target.v3+json' \
-H 'x-api-key: <your-api-token>'
-d '{
"name": "New Activity Name",
"state": "approved",
"priority": 10,
"locations": {
"mboxes": [
{
"locationLocalId": 0,
"name": "mbox_1"
},
{
"locationLocalId": 1,
"name": "mbox_2"
},
{
"locationLocalId": 2,
"name": "mbox_3"
}
]
},
"experiences": [
{
"experienceLocalId": 0,
"name": "Tom Hanks Cast Away",
"offerLocations": [
{
"locationLocalId": 0,
"offerId": 400546
},
{
"locationLocalId": 1,
"offerId": 400547
},
{
"locationLocalId": 2,
"offerId": 400546
}
]
},
{
"experienceLocalId": 1,
"name": "Default",
"offerLocations": [
{
"locationLocalId": 0,
"offerId": 400546
},
{
"locationLocalId": 1,
"offerId": 400547
},
{
"locationLocalId": 2,
"offerId": 400546
}
]
}
],
"metrics": [
{
"metricLocalId": 3,
"name": "display about",
"mboxes": [
{
"name": "event_1",
"successEvent": "mbox_shown"
}
]
},
{
"metricLocalId": 4,
"name": "display hero",
"mboxes": [
{
"name": "event_2",
"successEvent": "mbox_shown"
}
]
},
{
"metricLocalId": 32767,
"name": "display userimg",
"conversion": true,
"action": {
"type": "count_once"
},
"mboxes": [
{
"name": "event_3",
"successEvent": "mbox_shown"
}
]
}
],
"workspace": "1234567",
"propertyIds": [
1,
2
],
"analytics": {
"reportSuite": "mydemoreportsuite",
"dataCollectionHost": "mydemoreportsuite.sc.omniture.com"
}
}'
Sample Response for Update AB Activity
{
"name": "New Activity Name",
"state": "approved",
"priority": 10,
"locations": {
"mboxes": [
{
"locationLocalId": 0,
"name": "mbox_1"
},
{
"locationLocalId": 1,
"name": "mbox_2"
},
{
"locationLocalId": 2,
"name": "mbox_3"
}
]
},
"experiences": [
{
"experienceLocalId": 0,
"name": "Tom Hanks Cast Away",
"offerLocations": [
{
"locationLocalId": 0,
"offerId": 400546
},
{
"locationLocalId": 1,
"offerId": 400547
},
{
"locationLocalId": 2,
"offerId": 400546
}
]
},
{
"experienceLocalId": 1,
"name": "Default",
"offerLocations": [
{
"locationLocalId": 0,
"offerId": 400546
},
{
"locationLocalId": 1,
"offerId": 400547
},
{
"locationLocalId": 2,
"offerId": 400546
}
]
}
],
"metrics": [
{
"metricLocalId": 3,
"name": "display about",
"mboxes": [
{
"name": "event_1",
"successEvent": "mbox_shown"
}
]
},
{
"metricLocalId": 4,
"name": "display hero",
"mboxes": [
{
"name": "event_2",
"successEvent": "mbox_shown"
}
]
},
{
"metricLocalId": 32767,
"name": "display userimg",
"conversion": true,
"action": {
"type": "count_once"
},
"mboxes": [
{
"name": "event_3",
"successEvent": "mbox_shown"
]
}
],
"workspace": "1234567",
"propertyIds": [
1,
2
],
"analytics": {
"reportSuite": "mydemoreportsuite",
"dataCollectionHost": "mydemoreportsuite.sc.omniture.com"
}
}
PUT: /{tenant}/target/activities/ab/{id}
Updates the AB activity definition with the contents as provided in the request. This can change the state and behaviour of an existing activity.
Get XT Activity by ID
Sample Request for Get XT Activity by ID
curl -X GET
https://mc.adobe.io/<your-tenant-name>/target/activities/xt/168824 \
-H 'authorization: Bearer <your-bearer-token>' \
-H 'cache-control: no-cache' \
-H 'Accept: application/vnd.adobe.target.v3+json' \
-H 'x-api-key: <your-api-token>'
Sample Response for Get XT Activity by ID
{
"id": 166425,
"thirdPartyId": "04662c10-0831-4306-bb36-5410acc88dff",
"name": "Master - Mobile - XT",
"state": "approved",
"priority": 999,
"autoAllocateTraffic": {
"enabled": false,
"successEvaluationCriteria": "conversion_rate"
},
"locations": {
"mboxes": [
{
"locationLocalId": 0,
"name": "a1-mobile-xt"
}
]
},
"experiences": [
{
"experienceLocalId": 0,
"name": "Silver",
"audienceIds": [
1209736
],
"offerLocations": [
{
"locationLocalId": 0,
"offerId": 393707
}
]
},
{
"experienceLocalId": 2,
"name": "Gold",
"audienceIds": [
1209737
],
"offerLocations": [
{
"locationLocalId": 0,
"offerId": 395545
}
]
},
{
"experienceLocalId": 3,
"name": "Sapphire",
"audienceIds": [
1209738
],
"offerLocations": [
{
"locationLocalId": 0,
"offerId": 393708
}
]
}
],
"metrics": [
{
"metricLocalId": 32767,
"name": "metric_placeholder",
"conversion": true,
"mboxes": [
{
"name": "conversion_placeholder",
"successEvent": "mbox_shown"
}
],
"action": {
"type": "count_once"
}
}
],
"workspace": "1234567",
"propertyIds": [
1,
2
],
"analytics": {
"reportSuite": "<your-tenant-name>iosdemo",
"dataCollectionHost": "<your-tenant-name>.sc.omtrdc.net"
},
"modifiedAt": "2017-06-12T14:27:44Z"
}
Gets a Experience Targeted activity that is referenced by the id.
Delete XT Activity by ID
Sample Request for Delete XT Activity by ID
curl -X DELETE \
https://mc.adobe.io/<your-tenant-name>/target/activities/xt/168333 \
-H 'authorization: Bearer <your-bearer-token>' \
-H 'cache-control: no-cache' \
-H 'Accept: application/vnd.adobe.target.v3+json' \
-H 'x-api-key: <your-api-token>'
Sample Response for Delete XT Activity by ID
{
"id": 168333,
"thirdPartyId": "60cc9620-999f-4052-bdad-1567838db10d_1499659779896",
"name": "My XT Activity",
"state": "deleted",
"priority": 0,
"autoAllocateTraffic": {
"enabled": false,
"successEvaluationCriteria": "conversion_rate"
},
"locations": {
"mboxes": [
{
"locationLocalId": 0,
"name": "j1-mobile-xt"
}
]
},
"experiences": [
{
"experienceLocalId": 0,
"name": "Experience A",
"audienceIds": [
1209736
],
"offerLocations": [
{
"locationLocalId": 0,
"offerId": 393707
}
]
},
{
"experienceLocalId": 1,
"name": "Experience B",
"audienceIds": [
1209737
],
"offerLocations": [
{
"locationLocalId": 0,
"offerId": 0
}
]
},
{
"experienceLocalId": 2,
"name": "Experience C",
"audienceIds": [
1209738
],
"offerLocations": [
{
"locationLocalId": 0,
"offerId": 0
}
]
}
],
"metrics": [
{
"metricLocalId": 32767,
"name": "MY PRIMARY GOAL",
"conversion": true,
"mboxes": [
{
"name": "order-complete",
"successEvent": "mbox_shown"
}
],
"action": {
"type": "count_once"
}
}
],
"workspace": "1234567",
"propertyIds": [
1,
2
],
"modifiedAt": "2017-07-10T04:09:39Z"
}
DELETE /{tenant}/target/activities/xt/{id}
Deletes the XT activity that is referenced by the id, if it is found.
Create XT Activity
Sample Request for Create XT Activity
curl -X POST \
https://mc.adobe.io/<your-tenant-name>/target/activities/xt/ \
-H 'authorization: Bearer <your-bearer-token>' \
-H 'cache-control: no-cache' \
-H 'content-type: application/vnd.adobe.target.v3+json' \
-H 'x-api-key: <your-api-token>'
-d '{
"name": "New XT API Activity",
"state": "saved",
"priority": 10,
"autoAllocateTraffic": {
"enabled": false,
"successEvaluationCriteria": "conversion_rate"
},
"locations": {
"mboxes": [
{
"locationLocalId": 0,
"name": "a1-serverside-xt"
}
]
},
"experiences": [
{
"experienceLocalId": 0,
"name": "USA Experience",
"audienceIds": [
1224696
],
"offerLocations": [
{
"locationLocalId": 0,
"offerId": 396067
}
]
},
{
"experienceLocalId": 1,
"name": "UK Experience",
"audienceIds": [
1224698
],
"offerLocations": [
{
"locationLocalId": 0,
"offerId": 396064
}
]
},
{
"experienceLocalId": 2,
"name": "France Experience",
"audienceIds": [
1224699
],
"offerLocations": [
{
"locationLocalId": 0,
"offerId": 396065
}
]
},
{
"experienceLocalId": 3,
"name": "Australia Experience",
"audienceIds": [
1224700
],
"offerLocations": [
{
"locationLocalId": 0,
"offerId": 396066
}
]
}
],
"metrics": [
{
"metricLocalId": 32767,
"name": "metric_placeholder",
"conversion": true,
"mboxes": [
{
"name": "conversion_placeholder",
"successEvent": "mbox_shown"
}
],
"action": {
"type": "count_once"
}
}
],
"workspace": "1234567",
"propertyIds": [
1,
2
],
"analytics": {
"reportSuite": "<your-tenant-name>westeros",
"dataCollectionHost": "<your-tenant-name>.sc.omtrdc.net"
}
}'
Sample Response for Create XT Activity
{
"id": 183919,
"name": "New XT API Activity",
"state": "saved",
"priority": 10,
"autoAllocateTraffic": {
"enabled": false,
"successEvaluationCriteria": "conversion_rate"
},
"locations": {
"mboxes": [
{
"locationLocalId": 0,
"name": "a1-serverside-xt"
}
]
},
"experiences": [
{
"experienceLocalId": 0,
"name": "USA Experience",
"audienceIds": [
1224696
],
"offerLocations": [
{
"locationLocalId": 0,
"offerId": 396067
}
]
},
{
"experienceLocalId": 1,
"name": "UK Experience",
"audienceIds": [
1224698
],
"offerLocations": [
{
"locationLocalId": 0,
"offerId": 396064
}
]
},
{
"experienceLocalId": 2,
"name": "France Experience",
"audienceIds": [
1224699
],
"offerLocations": [
{
"locationLocalId": 0,
"offerId": 396065
}
]
},
{
"experienceLocalId": 3,
"name": "Australia Experience",
"audienceIds": [
1224700
],
"offerLocations": [
{
"locationLocalId": 0,
"offerId": 396066
}
]
}
],
"metrics": [
{
"metricLocalId": 32767,
"name": "metric_placeholder",
"conversion": true,
"mboxes": [
{
"name": "conversion_placeholder",
"successEvent": "mbox_shown"
}
],
"action": {
"type": "count_once"
}
}
],
"workspace": "1234567",
"propertyIds": [
1,
2
],
"analytics": {
"reportSuite": "<your-tenant-name>westeros",
"dataCollectionHost": "<your-tenant-name>.sc.omtrdc.net"
},
"modifiedAt": "2017-07-10T06:01:27Z"
}
Creates a new XT activity with the specified contents and returns the created activity.
Update XT Activity
PUT: /{tenant}/target/activities/xt/{id}
Updates the Experience Targeted activity definition with the contents as provided in the request. This can change the state and behaviour of an existing activity.
Update Activity Name
Sample Request for Update Activity Name (Rename Activity)
curl -X PUT \
https://mc.adobe.io/<your-tenant-name>/target/activities/168816/name \
-H 'authorization: Bearer <your-bearer-token>' \
-H 'cache-control: no-cache' \
-H 'content-type: application/vnd.adobe.target.v1+json' \
-H 'x-api-key: <your-api-token>'
-d '{
"name": "New Name for Activity"
}'
Sample Response for Update Activity Name
{
"id": 168816,
"name": "New Name for Activity",
"modifiedAt": "2017-01-01T00:00Z"
}
Updates the name of the AB activity that is referenced by the supplied id.
PUT: /{tenant}/target/activities/{id}/name
Update Activity State
Sample Request for Update Activity State
curl -X PUT \
https://mc.adobe.io/<your-tenant-name>/target/activities/168816/state \
-H 'authorization: Bearer <your-bearer-token>' \
-H 'cache-control: no-cache' \
-H 'content-type: application/vnd.adobe.target.v1+json' \
-H 'x-api-key: <your-api-token>'
-d '{
"state": "deactivated"
}'
Sample Response for Update Activity State
{
"id": 168816,
"state": "deactivated",
"modifiedAt": "2017-01-01T00:00Z"
}
Update state for an activity that is referenced by the provided id. Valid values are:
- approved : corresponds to Live in Target UI.
- deactivated : corresponds to Inactive in Target UI.
- saved : corresponds to Inactive in Target UI.
PUT: /{tenant}/target/activities/{id}/state
Update Activity Priority
Sample Request for Update Activity Priotity
curl -X PUT \
https://mc.adobe.io/<your-tenant-name>/target/activities/168816/priority \
-H 'authorization: Bearer <your-bearer-token>' \
-H 'cache-control: no-cache' \
-H 'content-type: application/vnd.adobe.target.v1+json' \
-H 'x-api-key: <your-api-token>'
-d '{
"priority": "100"
}'
Sample Response for Update Activity Priotity
{
"id": 168816,
"priority": 100,
"modifiedAt": "2017-01-01T00:00Z"
}
Change priority for the AB activity that is referenced by the supplied id. Allowed values for priority are 0-999. If you are using low, medium and high in the Target UI, those correspond to 0,5 and 10 respectively. You need to turn granular priority on in the settings page inorder to use the 0-999 scale.
PUT: /{tenant}/target/activities/{id}/priority
Update Activity Schedule
Sample Request for Update Activity Schedule
curl -X PUT \
https://mc.adobe.io/<your-tenant-name>/target/activities/168816/schedule \
-H 'authorization: Bearer <your-bearer-token>' \
-H 'cache-control: no-cache' \
-H 'content-type: application/vnd.adobe.target.v1+json' \
-H 'x-api-key: <your-api-token>'
-d '{
"startsAt": "2017-05-01T08:00Z",
"endsAt": "2017-09-01T07:59:59Z"
}'
Sample Response for Update Activity Schedule
{
"id": 168816,
"startsAt": "2017-05-01T08:00Z",
"endsAt": "2017-09-01T07:59:59Z",
"modifiedAt": "2017-01-01T00:00Z"
}
PUT: /{tenant}/target/activities/{id}/schedule
Update the startsAt and endsAt fields of the AB activity referenced by the provided id. The schedule defines the start and end date and time for the activity. You need to pass the startsAt and endsAt values. If successful, it returns a status code 200. startsAt and endsAt support ISO 8601 style date-hour formats.
- yyyy-MM-dd’T'HH:mm:ssXXX
- yyyy-MM-dd’T'HH:mm:ss
- yyyy-MM-dd’T'HH
- yyyy-MM-dd
- yyyy-MM-dd’T'HH:mm:ss.SSS
- yyyy-MM-dd’T'HH:mm:ss.SSSXXX
Get Activity Changelog
Sample Request for Get Activity Changelog
curl -X GET \
https://mc.adobe.io/<your-tenant-name>/target/activities/173980/changelog \
-H 'authorization: Bearer <your-bearer-token>' \
-H 'cache-control: no-cache' \
-H 'content-type: application/vnd.adobe.target.v1+json' \
-H 'x-api-key: <your-api-token>'
Sample Response for Get Activity Changelog
{
"offset": 0,
"limit": 2147483647,
"total": 23,
"activityChangelogs": [
{
"modifiedAt": "2017-05-11T12:16:13Z",
"activityParameters": {
"state": {
"previousValue": "approved",
"changedValue": "saved"
}
}
},
{
"modifiedAt": "2017-04-27T14:57:32Z",
"activityParameters": {
"activityName": {
"previousValue": "Mobile Webinar - Micro Soft Permission",
"changedValue": "Mobile Webinar - Soft Permission"
}
}
},
{
"modifiedAt": "2017-04-27T14:57:32Z",
"modifiedOffer": {
"id": 426963,
"name": "/master_-_mobile_-abcopy/experiences/1/pages/0/zones/0/1493301097428"
}
},
{
"modifiedAt": "2017-04-27T14:09:44Z",
"activityParameters": {
"state": {
"previousValue": "approved",
"changedValue": "saved"
}
}
},
{
"modifiedAt": "2017-04-27T13:56:03Z",
"activityLocationOfferChange": {
"changedValue": {
"id": 426963,
"name": "/master_-_mobile_-abcopy/experiences/1/pages/0/zones/0/1493301097428"
},
"previousValue": {
"id": 391902,
"name": "10OFF"
},
"mbox": {
"name": "a1-mobile-ab",
"locationLocalId": 0
},
"experience": {
"name": "Always",
"experienceLocalId": 1
}
}
},
{
"modifiedAt": "2017-04-27T13:56:03Z",
"modifiedOffer": {
"id": 426962,
"name": "/master_-_mobile_-abcopy/experiences/0/pages/0/zones/0/1493301097401"
}
},
{
"modifiedAt": "2017-04-27T13:51:38Z",
"activityParameters": {
"state": {
"changedValue": "saved"
}
}
}
]
}
GET /{tenant}/target/activities/{id}/changelog
Returns the changelog for a given activity id.
Offers
API methods to Create, Read, Update and Delete Offers. Offers are also referred to as Content.
List Offers
Sample Request for List Offers
curl -X GET \
'https://mc.adobe.io/<your-tenant-name>/target/offers?limit=10' \
-H 'authorization: Bearer <your-bearer-token>' \
-H 'cache-control: no-cache' \
-H 'Accept: application/vnd.adobe.target.v2+json' \
-H 'x-api-key: <your-api-token>'
Sample Response for List Offers
{
"total": 1120,
"offset": 0,
"limit": 10,
"offers": [
{
"id": 391769,
"name": "/l1_a_b_test/experiences/0/pages/0/zones/0/1489440825492",
"type": "content",
"modifiedAt": "2017-03-20T03:03:28Z",
"workspace": "1234567"
},
{
"id": 391902,
"name": "10OFF",
"type": "content",
"modifiedAt": "2017-03-19T00:06:47Z",
"workspace": "1234567"
},
{
"id": 391903,
"name": "SHIPFREE",
"type": "content",
"modifiedAt": "2017-03-19T00:06:29Z",
"workspace": "1234567"
},
{
"id": 391904,
"name": "5OFF",
"type": "content",
"modifiedAt": "2017-03-19T00:06:26Z",
"workspace": "1234567"
},
{
"id": 391905,
"name": "/a1_-_l4206a_-_ab/experiences/0/pages/0/zones/0/1489468580249",
"type": "content",
"modifiedAt": "2017-06-30T19:48:38Z",
"workspace": "1234567"
},
{
"id": 391906,
"name": "/a1_-_l4206a_-_ab/experiences/1/pages/0/zones/0/1489468580252",
"type": "content",
"modifiedAt": "2017-06-14T20:24:39Z",
"workspace": "1234567"
},
{
"id": 391907,
"name": "/a1_-_l4206a_-_ab/experiences/2/pages/0/zones/0/1489468580255",
"type": "content",
"modifiedAt": "2017-04-21T21:34:55Z",
"workspace": "1234567"
},
{
"id": 391910,
"name": "/a1_-_l4206a_-_xt/experiences/0/pages/0/zones/0/1489470215324",
"type": "content",
"modifiedAt": "2017-03-19T03:51:21Z",
"workspace": "1234567"
},
{
"id": 391911,
"name": "/a1_-_l4206a_-_xt/experiences/1/pages/0/zones/0/1489470215327",
"type": "content",
"modifiedAt": "2017-03-14T05:43:36Z",
"workspace": "1234567"
},
{
"id": 391919,
"name": "/a1_-_l4206a_-_xt/experiences/2/pages/0/zones/0/1489474831626",
"type": "content",
"modifiedAt": "2017-03-19T03:51:21Z",
"workspace": "1234567"
}
]
}
GET /{tenant}/target/offers
Retrieve the list of previously-created content offers. The parameters passed through the query string are optional and are used to indicate the sorting and filtering options.
| Parameter | Description | Example |
|---|---|---|
| limit |
Defines the number of items to return. Default value is 2147483647. |
Returns the first ten offers
|
| offset |
Defines the first offer to return from the list of total offers. Used in conjunction with limit, you can provide pagination in your application for users to browse through a large set of offers. |
Returns the first ten offers |
| sortBy |
Defines the sorting criteria on the returned items. You can add a “-” modifier to sort by descending order. |
Returns the first ten offers sorted by ID Returns the first ten offers sorted in descending order by ID Returns the first ten offers sorted by ascending IDs and descending names
|
Get Offer by ID
Sample Request for Get Offer by ID
curl -X GET \
https://mc.adobe.io/<your-tenant-name>/target/offers/content/391902 \
-H 'authorization: Bearer <your-bearer-token>' \
-H 'cache-control: no-cache' \
-H 'Accept: application/vnd.adobe.target.v2+json' \
-H 'x-api-key: <your-api-token>'
Sample Response for Get Offer by ID
{
"id": 391902,
"name": "10OFF",
"content": "Use 10OFF for $10 off for orders over $100",
"modifiedAt": "2017-03-19T00:06:47Z",
"workspace": "1234567"
}
GET /{tenant}/target/offers/content/{id}
Retrieves the contents of an offer given an offer id.
Create Offer
Sample Request for Create Offer
curl -X POST \
https://mc.adobe.io/<your-tenant-name>/target/offers/content \
-H 'authorization: Bearer <your-bearer-token>' \
-H 'cache-control: no-cache' \
-H 'content-type: application/vnd.adobe.target.v2+json' \
-H 'x-api-key: <your-api-token>'
-d ' {
"name": "My new offer",
"content": "<div>The content of the offer</div>",
"workspace": "1234567"
}
'
Sample Response for Create Offer
{
"id": 438180,
"name": "My new offer",
"content": "<div>The content of the offer</div>",
"modifiedAt": "2017-07-10T20:46:53Z",
"workspace": "1234567"
}
POST: /{tenant}/target/offers/content
Creates a new content offer as defined by the request data.
| Attribute | Type | Description |
|---|---|---|
| name | String | A string to identify the Offer. The name cannot be empty. Max length is 250 characters. |
| content | String | Content of an Offer shown to user. |
| workspace | String | Optional id of workspace to which the activity belongs. Max length is 250 characters. By default, Default workspace is assumed. Applicable for Enterprise Permissions (Target Premium). |
Update Offer by ID
Sample Request for Update Offer by ID
curl -X PUT \
https://mc.adobe.io/<your-tenant-name>/target/offers/content/438180 \
-H 'authorization: Bearer <your-bearer-token>' \
-H 'cache-control: no-cache' \
-H 'content-type: application/vnd.adobe.target.v2+json' \
-H 'x-api-key: <your-api-token>'
-d ' {
"name": "Your existing offer",
"content": "<div>Updated content</div>"
}
'
Sample Response for Update Offer by ID
{
"id": 438180,
"name": "Your existing offer",
"content": "<div>Updated content</div>",
"modifiedAt": "2017-07-10T20:55:41Z"
}
PUT /{tenant}/target/offers/content/{id}
Updates the content offer referenced by the id specified in the URL.
Delete Offer by ID
Sample Request for Delete Offer by ID
curl -X DELETE \
https://mc.adobe.io/<your-tenant-name>/target/offers/content/438180 \
-H 'authorization: Bearer <your-bearer-token>' \
-H 'cache-control: no-cache' \
-H 'Accept: application/vnd.adobe.target.v2+json' \
-H 'x-api-key: <your-api-token>'
Sample Response for Delete Offer by ID
{
"id": 438180,
"name": "Your existing offer",
"content": "<div>Updated content</div>",
"modifiedAt": "2017-07-10T20:55:41Z",
"workspace": "1234567"
}
DELETE /{tenant}/target/offers/content/{id}
Deletes the content offer referenced by the provided id.
Audiences
API methods to Create, Read, Update and Delete Audiences.
List Audiences
Sample Request for List Audiences
curl -X GET \
'https://mc.adobe.io/<your-tenant-name>/target/audiences/' \
-H 'authorization: Bearer <your-bearer-token>' \
-H 'cache-control: no-cache' \
-H 'Accept: application/vnd.adobe.target.v3+json' \
-H 'x-api-key: <your-api-token>'
Sample Response for List Audiences
{
"offset": 0,
"limit": 10,
"total": 289,
"audiences": [
{
"id": 1216090,
"name": "A1 - Active account l-1489628809975",
"description": "--",
"origin": "target",
"modifiedAt": "2017-03-16T01:47:07Z",
"workspace": "1234567"
},
{
"id": 1216183,
"name": "A1 - Current Category -1489642111631",
"description": "--",
"origin": "target",
"modifiedAt": "2017-03-16T05:28:33Z",
"workspace": "1234567"
},
{
"id": 1216184,
"name": "A1 - Current category -1489642149723",
"description": "--",
"origin": "target",
"modifiedAt": "2017-03-16T05:29:11Z",
"workspace": "1234567"
},
{
"id": 1222658,
"name": "A1 - Customer Attribute -1489821120208",
"description": "--",
"origin": "target",
"modifiedAt": "2017-03-18T07:45:41Z",
"workspace": "1234567"
},
{
"id": 1238132,
"name": "A1 - L206 - Profile - -1490293696694",
"description": "--",
"origin": "target",
"modifiedAt": "2017-03-23T18:28:19Z",
"workspace": "1234567"
},
{
"id": 1238133,
"name": "A1 - L206 - Profile - -1490293722988",
"description": "--",
"origin": "target",
"modifiedAt": "2017-03-23T18:28:43Z",
"workspace": "1234567"
},
{
"id": 1238134,
"name": "A1 - L206 - Profile - -1490293734000",
"description": "--",
"origin": "target",
"modifiedAt": "2017-03-23T18:28:55Z",
"workspace": "1234567"
},
{
"id": 1238135,
"name": "A1 - L206 - Profile - -1490293749957",
"description": "--",
"origin": "target",
"modifiedAt": "2017-03-23T18:29:12Z",
"workspace": "1234567"
},
{
"id": 1235754,
"name": "A1 - L4206 - Alec - Us-1490221177054",
"description": "--",
"origin": "target",
"modifiedAt": "2017-03-22T22:19:38Z",
"workspace": "1234567"
},
{
"id": 1229960,
"name": "A1 - L4206 - Cart Amou-1490140690240",
"description": "--",
"origin": "target",
"modifiedAt": "2017-03-22T01:40:55Z",
"workspace": "1234567"
}
]
}
GET: /{tenant}/target/audiences
List all available audiences with options to filter and sort by each available field.
You can use the URL parameters to define pagination properties and sorting order of the list of audiences returned by this method.
| Parameter | Description | Example |
|---|---|---|
| limit |
Defines the number of items to return. Default value is 2147483647. |
Returns the first ten audiences
|
| offset |
Defines the first audience to return from the list of total offers. Used in conjunction with limit, you can provide pagination in your application for users to browse through a large set of offers. |
Returns the first ten audiences |
| sortBy |
Defines the sorting criteria on the returned items. You can add a “-” modifier to sort by descending order. |
Returns the first ten audiences sorted by ID Returns the first ten audiences sorted in descending order by ID Returns the first ten audiences sorted by ascending IDs and descending names
|
Some Additonal Examples
GET list of all audiences
https://mc.adobe.io/{tenant}/target/audiences/
GET audiences list with limit
https://mc.adobe.io/{tenant}/target/audiences/?limit=1
GET audiences list with limit and offset
https://mc.adobe.io/{tenant}/target/audiences/?limit=2&offset=2
GET audiences list filtered by multiple values
https://mc.adobe.io/{tenant}/target/audiences/?id=3&id=4&name=ab
GET audiences list filtered by negative values
https://mc.adobe.io/{tenant}/target/audiences/?priority=!4
GET audiences list sorted by multiple criteria
https://mc.adobe.io/{tenant}/target/audiences/?sortBy=name&sortBy=id
GET audiences list filtered by a date range
https://mc.adobe.io/{tenant}/target/audiences/?startsAt=1800-09-01T02:04:00.000-07:00/2114-11-30T14:10:00.000-07:00
Get Audience by ID
Sample Request for Get Audience by ID
curl -X GET \
https://mc.adobe.io/<your-tenant-name>/target/audiences/1397972 \
-H 'authorization: Bearer <your-bearer-token>' \
-H 'cache-control: no-cache' \
-H 'Accept: application/vnd.adobe.target.v3+json' \
-H 'x-api-key: <your-api-token>'
Sample Response for Get Audience by ID
{
"id": 1397972,
"name": "Gold Members in Califo-1495136673062",
"description": "--",
"origin": "target",
"targetRule": {
"and": [
{
"profile": "memberLevel",
"equals": [
"gold"
]
},
{
"geo": "region",
"matches": [
"california"
]
}
]
},
"modifiedAt": "2017-05-18T19:44:34Z",
"workspace": "1234567"
}
GET: /{tenant}/target/audiences/{id}
Get the audience definition specified by the provided id.
Create Audience
Sample Request for Create Audience
curl -X POST \
https://mc.adobe.io/<your-tenant-name>/target/audiences \
-H 'authorization: Bearer <your-bearer-token>' \
-H 'cache-control: no-cache' \
-H 'content-type: application/vnd.adobe.target.v3+json' \
-H 'x-api-key: <your-api-token>'
-d '{
"name": "Homepage visitors from California",
"description":"Description for my audience",
"targetRule": {
"and": [
{
"page": "url",
"equals":[
"http://www.myhomepage.com/"
]
},
{
"geo": "region",
"matches": [
"california"
]
}
]
},
"workspace": "1234567"
}'
Sample Request for Create Audience
{
"id": 1537195,
"name": "Homepage visitors from California",
"description": "Description for my audience",
"origin": "target",
"targetRule": {
"and": [
{
"page": "url",
"equals": [
"http://www.myhomepage.com/"
]
},
{
"geo": "region",
"matches": [
"california"
]
}
]
},
"modifiedAt": "2017-07-10T22:24:04Z",
"workspace": "1234567"
}
POST /{tenant}/target/audiences
Create a new audience as specified by the contents of the request and return the newly-created audience definition.
Each audience definition is made up of either target or audience rules.
- Target rules allow the API caller to define conjunctions (OR) or disjunctions (AND) between various targeting conditions.
- Audience rules allow the API caller to build conjunctions (OR) or disjunctions over pre-built audiences (referred by ids) to create even more powerful definitions
targetRules and audienceRule cannot be mixed within the same audience definition.
| Attribute | Type | Description |
|---|---|---|
| name | String | A unique name for the audience |
| description | String | A description for the audience |
| targetRule | Array | An array of rule objects containing logical target statements using operators such as AND, OR, EQUALS, etc. |
| audienceRule | Array |
An array of rule objects that refer to pre-built audiences referred by their IDs |
| workspace | String | Optional id of workspace to which the activity belongs. Max length is 250 characters. By default, Default workspace is assumed. Applicable for Enterprise Permissions (Target Premium). |
Update Audience by ID
Sample Request for Update Audience by ID
curl -X PUT \
https://mc.adobe.io/<your-tenant-name>/target/audiences/1537195 \
-H 'authorization: Bearer <your-bearer-token>' \
-H 'cache-control: no-cache' \
-H 'content-type: application/vnd.adobe.target.v3+json' \
-H 'x-api-key: <your-api-token>'
-d '{
"name": "Homepage visitors from California",
"description":"Description for my audience",
"targetRule": {
"and": [
{
"page": "url",
"equals":[
"http://www.mynewhomepage.com/"
]
},
{
"geo": "region",
"matches": [
"california"
]
}
]
}
}'
Sample Request for Update Audience by ID
{
"id": 1537195,
"name": "Homepage visitors from California",
"description": "Description for my audience",
"origin": "target",
"targetRule": {
"and": [
{
"page": "url",
"equals": [
"http://www.mynewhomepage.com/"
]
},
{
"geo": "region",
"matches": [
"california"
]
}
]
},
"modifiedAt": "2017-07-10T22:29:28Z",
"workspace": "1234567"
}
PUT /{tenant}/target/audiences/{id}
Update an audience with the new rules specified by the request data.
Delete Audience by ID
Sample Request for Delete Audience by ID
curl -X DELETE \
https://mc.adobe.io/<your-tenant-name>/target/audiences/1537214 \
-H 'authorization: Bearer <your-bearer-token>' \
-H 'cache-control: no-cache' \
-H 'Accept: application/vnd.adobe.target.v3+json' \
-H 'x-api-key: <your-api-token>'
Sample Request for Delete Audience by ID
{
"id": 1537214,
"name": "New Audience",
"description": "Description for my audience",
"origin": "target",
"targetRule": {
"and": [
{
"page": "url",
"equals": [
"http://www.myhomepage.com/"
]
},
{
"geo": "region",
"matches": [
"california"
]
}
]
},
"modifiedAt": "2017-07-10T22:31:18Z",
"workspace": "1234567"
}
DELETE /{tenant}/target/audiences/{id}
Delete the audience referenced by the specified id.
Property
API methods for Properties. Applicable for Enterprise Permissions (Target Premium).
List Properties
Sample Request to retrieve list of all properties
curl -X GET \
https://mc.adobe.io/<your-tenant-name>/target/properties \
-H 'authorization: Bearer <your-bearer-token>' \
-H 'cache-control: no-cache' \
-H 'Accept: application/vnd.adobe.target.v1+json' \
-H 'x-api-key: <your-api-token>'
Sample Response for Get property
{
"total": 2,
"offset": 0,
"limit": 2147483647,
"properties": [
{
"id": 2,
"name": "Products pagde",
"description": "This property will be required on all pages under Products section of website",
"channel": "web",
"segmentId": 410923,
"modifiedAt": "2019-02-18T12:26:22.000Z",
"workspaces": [
"12",
"15"
]
},
{
"id": 1,
"name": "Products page",
"description": "This property will be required on all pages under Products section of website",
"channel": "web",
"segmentId": 410923,
"modifiedAt": "2019-02-18T12:25:20.000Z"
}
]
}
GET /{tenant}/target/properties
Retrieve list of all properties.
Get property by ID
Sample Request to retrieve property by property Id
curl -X GET \
https://mc.adobe.io/<your-tenant-name>/target/properties/{id} \
-H 'authorization: Bearer <your-bearer-token>' \
-H 'cache-control: no-cache' \
-H 'Accept: application/vnd.adobe.target.v1+json' \
-H 'x-api-key: <your-api-token>'
Sample Response for Get property by property Id.
{
"id": 1,
"name": "Email property",
"description": "This is a email type of property",
"channel": "email",
"segmentId": 5,
"workspaces": [
"1234567",
"12345679"
]
}
GET /{tenant}/target/properties/{id}
Retrieve property by property Id.
Reports
Get AB Performance Report
Sample Request for Get AB Performance Report
curl -X GET \
https://mc.adobe.io/<your-tenant-name>/target/activities/ab/166423/report/performance \
-H 'authorization: Bearer <your-bearer-token>' \
-H 'cache-control: no-cache' \
-H 'content-type: application/vnd.adobe.target.v1+json' \
-H 'x-api-key: <your-api-token>'
Sample Response for Get AB Performance Report
{
"reportParameters": {
"activityId": 166423,
"environmentId": 8818,
"conversionMetricLocalIds": [
32767
],
"reportInterval": "2017-03-14T05:00Z/2017-07-10T07:00Z"
},
"activity": {
"id": 166423,
"thirdPartyId": "f79c0aa0-44e4-4766-ab93-1bf11b781f84",
"type": "ab",
"state": "approved",
"name": "Master - Mobile - AB",
"priority": 999,
"modifiedAt": "2017-06-30T19:48:38Z",
"metrics": [
{
"name": "Entry",
"metricLocalId": 0
},
{
"name": "Display mboxes",
"metricLocalId": 2
},
{
"name": "metric_placeholder",
"metricLocalId": 32767
}
],
"experiences": [
{
"name": "5OFF",
"experienceLocalId": 0
},
{
"name": "SHIPFREE",
"experienceLocalId": 2
},
{
"name": "10OFF",
"experienceLocalId": 1,
"deletedAt": "2017-06-14T21:02:12.000Z"
}
]
},
"report": {
"statistics": {
"totals": {
"visitor": {
"totals": {
"entries": 115,
"conversions": 0
}
},
"visit": {
"totals": {
"entries": 274,
"conversions": 0
}
},
"impression": {
"totals": {
"entries": 328,
"conversions": 0
}
},
"landing": {
"totals": {
"entries": 328,
"conversions": 0
}
}
},
"experiences": [
{
"experienceLocalId": 0,
"totals": {
"visitor": {
"totals": {
"entries": 31,
"conversions": 0
}
},
"visit": {
"totals": {
"entries": 85,
"conversions": 0
}
},
"impression": {
"totals": {
"entries": 102,
"conversions": 0
}
},
"landing": {
"totals": {
"entries": 102,
"conversions": 0
}
}
}
},
{
"experienceLocalId": 1,
"totals": {
"visitor": {
"totals": {
"entries": 34,
"conversions": 0
}
},
"visit": {
"totals": {
"entries": 123,
"conversions": 0
}
},
"impression": {
"totals": {
"entries": 140,
"conversions": 0
}
},
"landing": {
"totals": {
"entries": 140,
"conversions": 0
}
}
}
},
{
"experienceLocalId": 2,
"totals": {
"visitor": {
"totals": {
"entries": 50,
"conversions": 0
}
},
"visit": {
"totals": {
"entries": 66,
"conversions": 0
}
},
"impression": {
"totals": {
"entries": 86,
"conversions": 0
}
},
"landing": {
"totals": {
"entries": 86,
"conversions": 0
}
}
}
}
]
}
}
}
GET /{tenant}/target/activities/ab/{id}/report/performance
Retrieve the performance report data for the AB activity referenced by the provided id.
Get XT Performance Report
Sample Request for Get XT Performance Report
curl -X GET \
https://mc.adobe.io/<your-tenant-name>/target/activities/xt/167169/report/performance \
-H 'authorization: Bearer <your-bearer-token>' \
-H 'cache-control: no-cache' \
-H 'content-type: application/vnd.adobe.target.v1+json' \
-H 'x-api-key: <your-api-token>'
Sample Response for Get XT Performance Report
{
"reportParameters": {
"activityId": 167169,
"environmentId": 8818,
"conversionMetricLocalIds": [
32767
],
"reportInterval": "2017-03-20T16:00Z/2017-07-10T07:00Z"
},
"activity": {
"id": 167169,
"thirdPartyId": "6116ec53-5a2b-4f5d-9268-41e4c153e494",
"type": "xt",
"state": "approved",
"name": "Master - Serverside - XT",
"priority": 0,
"modifiedAt": "2017-06-06T22:00:25Z",
"metrics": [
{
"name": "Entry",
"metricLocalId": 0
},
{
"name": "Display mboxes",
"metricLocalId": 2
},
{
"name": "metric_placeholder",
"metricLocalId": 32767
}
],
"experiences": [
{
"name": "USA Experience",
"experienceLocalId": 0
},
{
"name": "UK Experience",
"experienceLocalId": 1
},
{
"name": "France Experience",
"experienceLocalId": 2
},
{
"name": "Australia Experience",
"experienceLocalId": 3
}
]
},
"report": {
"statistics": {
"totals": {
"visitor": {
"totals": {
"entries": 41,
"conversions": 0
}
},
"visit": {
"totals": {
"entries": 52,
"conversions": 0
}
},
"impression": {
"totals": {
"entries": 72,
"conversions": 0
}
},
"landing": {
"totals": {
"entries": 72,
"conversions": 0
}
}
},
"experiences": [
{
"experienceLocalId": 0,
"totals": {
"visitor": {
"totals": {
"entries": 11,
"conversions": 0
}
},
"visit": {
"totals": {
"entries": 16,
"conversions": 0
}
},
"impression": {
"totals": {
"entries": 27,
"conversions": 0
}
},
"landing": {
"totals": {
"entries": 27,
"conversions": 0
}
}
}
},
{
"experienceLocalId": 1,
"totals": {
"visitor": {
"totals": {
"entries": 9,
"conversions": 0
}
},
"visit": {
"totals": {
"entries": 11,
"conversions": 0
}
},
"impression": {
"totals": {
"entries": 13,
"conversions": 0
}
},
"landing": {
"totals": {
"entries": 13,
"conversions": 0
}
}
}
},
{
"experienceLocalId": 2,
"totals": {
"visitor": {
"totals": {
"entries": 9,
"conversions": 0
}
},
"visit": {
"totals": {
"entries": 12,
"conversions": 0
}
},
"impression": {
"totals": {
"entries": 17,
"conversions": 0
}
},
"landing": {
"totals": {
"entries": 17,
"conversions": 0
}
}
}
},
{
"experienceLocalId": 3,
"totals": {
"visitor": {
"totals": {
"entries": 12,
"conversions": 0
}
},
"visit": {
"totals": {
"entries": 13,
"conversions": 0
}
},
"impression": {
"totals": {
"entries": 15,
"conversions": 0
}
},
"landing": {
"totals": {
"entries": 15,
"conversions": 0
}
}
}
}
]
}
}
}
GET /{tenant}/target/activities/xt/{id}/report/performance
Retrieve the performance report data for the Experience activity referenced by the provided id.
Get AP Activity Performance Report
GET /{tenant}/target/activities/abt/{id}/report/performance
Retrieve the performance report data for the Automated Personalization activity referenced by the provided id.
Get Audit Report
Sample Request for AB Audit Report
curl -X GET \
https://mc.adobe.io/<your-tenant-name>/target/activities/ab/167169/orders/performance \
-H 'authorization: Bearer <your-bearer-token>' \
-H 'cache-control: no-cache' \
-H 'content-type: application/vnd.adobe.target.v1+json' \
-H 'x-api-key: <your-api-token>'
Sample Response for AB and XT Audit Reports
{
"reportParameters": {
"activityId": 167169,
"environmentId": 8818,
"reportInterval": "2017-03-20T16:00Z/2017-08-19T00:01:01.721Z",
"conversionMetricLocalIds": [
32767
]
},
"activity": {
"id": 167169,
"thirdPartyId": "6116ec53-5a2b-4f5d-9268-41e4c153e494",
"type": "xt",
"state": "approved",
"name": "Master - Serverside - XT",
"priority": 0,
"modifiedAt": "2017-07-31T18:23:44Z",
"metrics": [
{
"name": "Entry",
"metricLocalId": 0
},
{
"name": "Display mboxes",
"metricLocalId": 2
},
{
"name": "metric_placeholder",
"metricLocalId": 32767
}
],
"experiences": [
{
"name": "USA Experience",
"experienceLocalId": 0
},
{
"name": "UK Experience",
"experienceLocalId": 1
},
{
"name": "France Experience",
"experienceLocalId": 2
},
{
"name": "Australia Experience",
"experienceLocalId": 3
}
]
},
"orders": [
{
"time": "2015-12-04T00:00:00.000-05:00",
"experienceLocalId": 0,
"id": "order ID 4444",
"total": 7.4,
"duplicate": true,
"outlier": true,
"productPurchasedIds": ["laptop3", "book3"]
},
{
"time": "2015-12-02T10:03:00.000-05:00",
"experienceLocalId": 1,
"id": "order REF ID#123",
"total": 23.01
},
...
]
}
Sample Response for AP Audit Reports.
"orders": [
{
"time": "2017-01-11T00:00:00.000-05:00",
"decisionStackId": 0,
"id": "1452535235728",
"total": 325,
"productIds": [
"5"
]
},
{
"time": "2017-01-11T00:00:00.000-05:00",
"decisionStackId": 1,
"id": "1452535342214",
"total": 325,
"productIds": [
"5"
]
},
{
"time": "2017-01-11T00:00:00.000-05:00",
"decisionStackId": 2,
"id": "1452535371489",
"total": 429,
"productIds": [
"9"
]
}
]
}
GET /{tenant}/target/activities/ab/{id}/report/orders
Retrieve the orders/audit report data for an AB, XT or Autotmated Personalization Activity
Mboxes and Environments
APIs to retrive mboxes, mbox paramaters, profile parmeters and environments.
List Mboxes
Sample Request for List Mboxes
curl -X GET \
https://mc.adobe.io/<your-tenant-name>/target/mboxes \
-H 'authorization: Bearer <your-bearer-token>' \
-H 'cache-control: no-cache' \
-H 'content-type: application/vnd.adobe.target.v1+json' \
-H 'x-api-key: <your-api-token>'
Sample Response for List Mboxes
{
"total": 12,
"offset": 0,
"limit": 5,
"mboxes": [
{
"name": "a1-mobile-aam",
"status": "active",
"lastRequestedAt": "2017-07-09T20:41:18.000Z"
},
{
"name": "a1-mobile-ab",
"status": "active",
"lastRequestedAt": "2017-07-04T10:22:59.000Z"
},
{
"name": "a1-mobile-mboxparams",
"status": "active",
"lastRequestedAt": "2017-07-09T21:13:36.000Z"
},
{
"name": "a1-mobile-profileparams",
"status": "active",
"lastRequestedAt": "2017-06-29T17:24:54.000Z"
},
{
"name": "a1-mobile-xt",
"status": "active",
"lastRequestedAt": "2017-07-04T10:19:21.000Z"
}
]
}
GET /{tenant}/target/mboxes
List all available mboxes for a specific client with the options to filter and sort.
List Mbox Parameters
Sample Request for List Mbox Parameters
curl -X GET \
'https://mc.adobe.io/<your-tenant-name>/target/mbox/a1-mobile-mboxparams?limit=5' \
-H 'authorization: Bearer <your-bearer-token>' \
-H 'cache-control: no-cache' \
-H 'content-type: application/vnd.adobe.target.v1+json' \
-H 'x-api-key: <your-api-token>'
Sample Response for List Mbox Parameters
{
"name": "a1-mobile-mboxparams",
"mboxParameters": [
{
"name": "a.AppID",
"parameterType": "MBOX"
},
{
"name": "a.CarrierName",
"parameterType": "MBOX"
},
{
"name": "a.CrashEvent",
"parameterType": "MBOX"
},
{
"name": "a.DailyEngUserEvent",
"parameterType": "MBOX"
},
{
"name": "a.DayOfWeek",
"parameterType": "MBOX"
},
{
"name": "a.DaysSinceFirstUse",
"parameterType": "MBOX"
},
{
"name": "a.DaysSinceLastUse",
"parameterType": "MBOX"
},
{
"name": "a.DeviceName",
"parameterType": "MBOX"
},
{
"name": "a.HourOfDay",
"parameterType": "MBOX"
},
{
"name": "a.LaunchEvent",
"parameterType": "MBOX"
},
{
"name": "a.Launches",
"parameterType": "MBOX"
},
{
"name": "a.MonthlyEngUserEvent",
"parameterType": "MBOX"
},
{
"name": "a.OSVersion",
"parameterType": "MBOX"
},
{
"name": "a.PrevSessionLength",
"parameterType": "MBOX"
},
{
"name": "a.Resolution",
"parameterType": "MBOX"
},
{
"name": "a.locale",
"parameterType": "MBOX"
},
{
"name": "a.ltv.amount",
"parameterType": "MBOX"
},
{
"name": "currentCategory",
"parameterType": "MBOX"
},
{
"name": "isloggedin",
"parameterType": "MBOX"
},
{
"name": "mboxAAMB",
"parameterType": "MBOX"
},
{
"name": "mboxMCGLH",
"parameterType": "MBOX"
},
{
"name": "mboxMCGVID",
"parameterType": "MBOX"
},
{
"name": "vst.member_guid.authState",
"parameterType": "MBOX"
},
{
"name": "vst.member_guid.id",
"parameterType": "MBOX"
},
{
"name": "vst.mycustomerid.authState",
"parameterType": "MBOX"
},
{
"name": "vst.mycustomerid.id",
"parameterType": "MBOX"
},
{
"name": "page.domain",
"parameterType": "MBOX"
},
{
"name": "page.param",
"parameterType": "MBOX"
},
{
"name": "page.protocol",
"parameterType": "MBOX"
},
{
"name": "page.query",
"parameterType": "MBOX"
},
{
"name": "page.url",
"parameterType": "MBOX"
},
{
"name": "page.path",
"parameterType": "MBOX"
},
{
"name": "page.fragment",
"parameterType": "MBOX"
},
{
"name": "landing.domain",
"parameterType": "MBOX"
},
{
"name": "landing.param",
"parameterType": "MBOX"
},
{
"name": "landing.protocol",
"parameterType": "MBOX"
},
{
"name": "landing.query",
"parameterType": "MBOX"
},
{
"name": "landing.url",
"parameterType": "MBOX"
},
{
"name": "landing.path",
"parameterType": "MBOX"
},
{
"name": "landing.fragment",
"parameterType": "MBOX"
},
{
"name": "referrer.domain",
"parameterType": "MBOX"
},
{
"name": "referrer.param",
"parameterType": "MBOX"
},
{
"name": "referrer.protocol",
"parameterType": "MBOX"
},
{
"name": "referrer.query",
"parameterType": "MBOX"
},
{
"name": "referrer.url",
"parameterType": "MBOX"
},
{
"name": "referrer.path",
"parameterType": "MBOX"
}
]
}
GET /{tenant}/target/mbox/{mboxName}
Get the list of mbox parameters.
List Profile Parameters
Sample Request for List Profile Parameters
curl -X GET \
https://mc.adobe.io/<your-tenant-name>/target/profileattributes/mbox \
-H 'authorization: Bearer <your-bearer-token>' \
-H 'cache-control: no-cache' \
-H 'content-type: application/vnd.adobe.target.v1+json' \
-H 'x-api-key: <your-api-token>'
Sample Response for List Profile Parameters
{
"mboxProfileAttributes": [
"activeAccounts",
"country",
"entity.id",
"entity.name",
"gotlastname",
"hasChecking",
"hasMortgage",
"hasRetirement",
"house",
"mbox3rdPartyId",
"memberLevel",
"nbalastname",
"param1",
"param2",
"playerName",
"qaExperience",
"transformerType"
]
}
GET /{tenant}/target/profileattributes/mbox
Retrieve the list of available profile attributes and mbox parameters of type profile
List Environments
Sample Request for List Environments
curl -X GET \
https://mc.adobe.io/<your-tenant-name>/target/environments \
-H 'authorization: Bearer <your-bearer-token>' \
-H 'cache-control: no-cache' \
-H 'content-type: application/vnd.adobe.target.v1+json' \
-H 'x-api-key: <your-api-token>'
Sample Response for List Environments
{
"total": 3,
"offset": 0,
"limit": 2147483647,
"environments": [
{
"id": 8820,
"name": "Development"
},
{
"id": 8818,
"name": "Production"
},
{
"id": 8819,
"name": "Staging"
}
]
}
GET : /{tenant}/target/environments
List all available environments with the options to filter and sort. Use the Environments API to retrieve the environment IDs corresponding to the various host groups set for the client.
Batch Updates
Multiple Admin APIs can be executed as a single batch request.
Execute Calls in Batch
Sample Request Object
{
"operations": [
{
"operationId": 1,
"dependsOnOperationIds~": [0],
"method": "POST",
"relativeUrl": "/v1/offers",
"headers~": [
{
"name": "Content-Type",
"value": "application/json"
}
],
"body~": {
"key": "value"
}
}
]
}
Sample Response Object
{
"results": [
{
"operationId": 1,
"skipped~": false,
"statusCode~": 200,
"headers~": [
{
"name": "Content-Type",
"value": "application/json; charset=UTF-8"
}
],
"body~": {
"id": 5
}
}
]
}
POST /{tenant}/target/batch
Stack multiple API calls together and execute them in a single batch.
Batching allows you to pass instructions for several operations in a single HTTP request. You can also specify dependencies between related operations (described in a section below). TNT will process each of your independent operations (possibly in parallel) and will process your dependent operations sequentially. Once all operations have been completed, a consolidated response will be passed back and the HTTP connection will be closed.
The batch API takes in an array of logical HTTP requests represented as JSON arrays - each request has a method (corresponding to HTTP method GET/PUT/POST/DELETE etc.), a relativeUrl (the portion of the URL after admin/rest/), optional headers array (corresponding to HTTP headers) and an optional body (for POST and PUT requests). The Batch API returns an array of logical HTTP responses represented as JSON arrays - each response has a status code, an optional headers array and an optional body (which is a JSON encoded string). To make batched requests build a JSON object which describes each individual operation to perform. The number of maximum allowed operations are 256 (from 0 to 255).
Specifying dependencies between operations in the request By default, the operations specified in the batch API request are independent - they can be executed in arbitrary order on the server and an error in one operation does not affect execution of other operations.
Often, the operations in the request are dependent - for example, the output of one operation may be used in the input of the next operation. For example offer created in operationId=0 needs to be used in campaign creation operationId=1.
In order to link two batch operations together specify in the dependent operation the id of the required operation, for instance: “dependsOnOperationId” : 5. Also IDs of created resources via POST requests of batch operations can be used in dependent operations both in “relativeUrl” and “body”.
Permissions & Throttling In order to execute batch API actions the underlying user has to have at least “editor” rights (for each individual operation in case additional rights are required than user has then the individual operation will fail). Usual throttling strategies are applied on batch API actions as if every operation has been performed individually.
Batch processing finishes when all operations have been completed, an operation could either be successful (2xx statusCode), failure (4xx, 5xx status code) or skipped because a dependency operation has failed or has been skipped.
Request Object Parameter
| Attribute | Description | Limits | Default |
|---|---|---|---|
|
body |
body for HTTP batch operation. will be ignored for all actions but POST and PUT. can refer to IDs from previous batch actions, for instance: “offerId”: “{operationIdResponse:0}”, “segmentId”: “{operationIdResponse:1}” |
|
empty object {} |
|
dependsOnOperationIds |
list of constraint IDs that will assure that current operation will execute only if specified operations have completed successfully. Can be used to achieve chaining of operations. |
|
- |
|
headers |
array of key-value headers to be sent with particular operation. In case authentication for batch API has been performed via Authorization header, it will be copied for individual operations as well. |
|
Content-Type: application/json |
|
headers->name |
header name |
|
- |
|
headers->value |
header value |
|
empty string |
|
method |
HTTP method to use. Available options: GET, POST, PUT, PATCH, DELETE |
|
- |
|
operationId |
operation ID used to identify an operation among other operations for responses and referencing results. |
|
- |
|
operations |
list of operations to perform in a batch. order is not relevant. |
|
- |
|
relativeUrl |
relative URL for admin rest API, the part after “/admin/rest/”. Can contain query string parameters like: “/v2/campaigns?limit=10&offset=10”. can refer to URLs with contain IDs from previous batch actions, for instance: “/v1/offers/{operationIdResponse:0}”. In case query parameters are sent they have to be URL encoded. |
| - |
Response Object Parameter
| Parameter | Description |
|---|---|
|
operationId |
operation ID used to identify an operation among other operations, same ID as it has been sent in POST request. |
|
skipped |
boolen flag to mark if operation has been executed or skipped. Will be true in case that current operation depends on a operation which has failed (returned a statusCode value different than 2xx). |
|
statusCode |
HTTP status code of operation identified by operationId. In case a different value than 2xx is returned then all depending operations will be skipped (not executed). |
|
headers |
array of key-value headers to be sent as a response for particular operation. |
|
headers->name |
header name |
|
headers->value |
header value |
|
body |
body for HTTP batch response operation |
Profiles
Adobe Target creates and maintains a profile for every individual user. This profile is stored on the Target edge cluster and is updated in real time after every visit.
Profiles Postman Collection
Postman is a application that makes it easy to fire API calls. This Postman collection contains all the Profile API calls. Just click on the 'Run in Postman’ button to import the Profile API collection.
Structure of a Target Profile
Sample Profile Structure
{
"client": "<your-tenant-name>",
"visitorId": "a1-mbox3rdPartyId",
"modifiedAt": "2017-08-18T17:53:39.003-04:00",
"profileAttributes": {
"insurance": {
"value": "false",
"modifiedAt": "2017-07-31T20:34:55.625-04:00"
},
"country": {
"value": "france",
"modifiedAt": "2017-07-31T14:26:30.879-04:00"
},
"checking": {
"value": "true",
"modifiedAt": "2017-07-31T20:34:55.625-04:00"
},
"user.memberlevel": {
"value": "0.0",
"modifiedAt": "2017-08-09T18:18:04.661-04:00"
},
"param1": {
"value": "value1",
"modifiedAt": "2017-08-09T18:18:04.659-04:00"
},
"param2": {
"value": "value2",
"modifiedAt": "2017-08-09T18:18:04.659-04:00"
},
"firstSessionStart": {
"value": "1500648715286",
"modifiedAt": "2017-07-21T10:51:55.286-04:00"
},
"entity.name": {
"value": "my-entityName",
"modifiedAt": "2017-08-09T18:18:04.659-04:00"
},
"entity.id": {
"value": "my-entityId",
"modifiedAt": "2017-08-09T18:18:04.659-04:00"
}
}
}
A Target Profile consists of these following objects
- clientcode - The Target client code to which the profile is associated visitorId - The identifier for the profile. This can be a tntid or thirdpartyid or marketingcloudvisitorid modifiedAt - The timestamp of when the profile was last updated. profileAttributes - List of all the profile attributes stored as key-value pairs on that the individual profile
Fetching a profile
A Target Profile can be fetched in two ways
Using a tnt id
Target automatically assigns a tntid for every request.
The request format to fetch a profile using a tntid
https://<your-client-code>.tt.omtrdc.net/rest/v1/profiles/your-tnt-id?client=<your-client-code>
Replace “
http://<your-client-code>.tt.omtrdc.net/rest/v1/profiles/111492025094307-353046?client=<your-client-code>
Using a thirdPartyId
Target profiles can be augmented with your own identifier (eg: CRM id, uuid, membership number etc). See the profile update section to learn how you can attach a thirdPartyId to your profile.
The request format to fetch a profile using a thirdPartyId
https://<your-client-code>.tt.omtrdc.net/rest/v1/profiles/thirdPartyId/your-thirdpartyid?<your-client-code>
Replace “
http://<your-client-code>.tt.omtrdc.net/rest/v1/profiles/thirdPartyId/a1-mbox3rdPartyId?client=<your-client-code>
When this call is made, Target attempts to locate the profile first in the cluster noted in the edge request, or wherever the profile is located and return the content. The profile contents are returned in JSON format.
Authentication
The Profile API can be secured by turning authentication on from the Target UI as described here. Once authentication is switched ON, all profile API requests must have the profile authentication token set in the request headers. The token itself can be generated using the Target UI or using the steps explained above in the Profile Authentication Token section.
Metering
These calls do not count towards your mbox calls.
Error Handling
In the case of a call to /thirdPartyId with an invalid or an expired thirdPartyId specified:
{"status" : 404, "message" : "No profile found for client <client_code> with third party id=<third_party_id>"}
If the profile can not be located or has expired:
{"status" : 404, "message" : "No profile found for client <client_code> with mboxPC=<mbox_pc>"}
Updating Profiles
A user profile contains demographic and behavioral information of a web page visitor, such as age, gender, products purchased, last time of visit, and so on that Target uses to personalize the content it serves to the visitor.
The profile information for each visitor is either stored in cookies or in third-party apps.
If your web page implements the Target code, the profile information from the cookies is passed to Target using profile parameters. Target identifies each visitor uniquely through a pcID that it generates the visitor’s cookies. However, you can pass profile parameters from an external app through mbox calls using mbox3rdPartyIds.
Use the profile APIs when you have profile data about your visitors to send to Target that you either can’t or don’t want to send as part of your page-based integration with Target. This might be data from a CRM or POS that isn’t available on the page, or data of a more sensitive nature that does not make sense to pass on the page.
There are two ways to update profiles via API:
- Single profile API
- Bulk profile update via batch
Single Profile Update
The Single Profile Update API allows sending a profile update for a single user and is generally used when an update must occur in relation to a transaction occurring in a channel that has not implemented Target.
The Single Profile Update API is limited to performing 1 million updates in any rolling 24-hour period. Updates generally occur in under 1 hour, but may take as long as 24 hours to be reflected. If you need to send more updates, or require updates to be processed in shorter timeframes, consider sending transactional profile updates via client-side update (preferred), or via the Server-Side Delivery API.
Specify the profile parameters in the format profile.paramName=value. To update the profile for a pcId, use:
https://<your-client-code>.tt.omtrdc.net/m2/client/profile/update?mboxPC=1368007744041-575948.01_00&profile.attr=0&profile.attr2=1...
To update the profile for an mbox3rdPartyId, use:
shell
http://<your-client-code>.tt.omtrdc.net/m2/client/profile/update?mbox3rdPartyId=123456&profile.attr=0&profile.attr2=1...
The Single Profile Update API is for updates only. If nothing is found, a profile is not created.
Notes
- Parameters and values must be URL-encoded using UTF-8.
- Parameter format is profile.paramName.
- Not all parameter values need to exist for all pcIds/mbox3rdPartyId.
- Parameters and values are case sensitive.
- Both GET and POST are supported.
- The current size limitations for limit is 8KB for GET and 60KB for POST.
Response
A sample response for the above requests looks like this.
trueRequest successfully submitted
This response indicates the response has been submitted and will be processed soon.
Bulk Profile Update
The Bulk Profile Update API allows you to update user profiles for multiple visitors to a website in bulk using a batch file.
Using Bulk Profile Update API, you can conveniently send detailed visitor profile data in the form of profile parameters for a bunch of users to Target from any external source, including CRM or POS, which isn’t usually available on a web page.
| Version | URL Example | Features |
|---|---|---|
| V1 | http://CLIENTCODE.tt.omtrdc.net/m2/ CLIENTCODE/profile/batchUpdate | Support for bulk profile update only |
| V2 | http://CLIENTCODE.tt.omtrdc.net/m2/ CLIENTCODE/v2/profile/batchUpdate |
|
version 2 (v2) of the Bulk Profile Update API is the current version. However, Target still supports version 1 (v1).
Caveats
- The size of the batch file must be less than 50 MB. In addition, the total number of rows should not exceed 500,000 rows per upload.
- There is no limit on the number or rows you can upload over a period of 24 hours in subsequent batches. However, the ingestion process might be throttled during business hours to ensure that other processes run efficiently.
- Consecutive V2 batch update calls without mbox calls in between for the same thirdPartyIds override the properties updated in the first batch update call.
Batch File
To update profile data in bulk, create a batch file. The batch file is a text file with values separated by commas similar to the following sample file.
batch=pcId, param1, param2, param3, param4 123, value1 124, value1,,, value4 125,, value2 126, value1, value2, value3, value4
You reference this file in the POST call to Target servers to process the file. When creating the batch file, bear in mind the following:
- The first row of the file must specify column headers.
- The first header should either be a pcId or thirdPartyId. The Marketing Cloud visitor ID is not supported. pcId is a Target-generated visitorID. thirdPartyId is an ID specified by the client application, which is passed to Target through an mbox call as mbox3rdPartyId. It must be referred to here as thirdPartyId.
- Parameters and values you specify in the batch file must be URL-encoded using UTF-8 for security reasons. They can be forwarded to other edge nodes for processing through HTTP requests.
- The parameters must be in the format paramName only. They are displayed in Target as profile.paramName.
- If you are using Bulk Profile Update API v2, you need not specify all parameter values for each pcId. Profiles are created for any pcId or mbox3rdPartyId that is not found in Target. If you are using v1, profiles are not created for missing pcIds or mbox3rdPartyIds.
- The size of the batch file must be less than 50MB. In addition, the total number of rows should not exceed 500,000. This limit ensures that servers don’t get flooded with too many requests.
- You can send multiple files. However, the sum total of the rows of all the files that you send in a day should not exceed one million for each client.
- There is no limit on number of attributes you upload. However, the overall size of a profile including system data should not exceed 2000KB. Adobe recommends you use less than 1000KB of storage for profile attributes.
- Parameters and values are case sensitive.
HTTP Post Request
Make an HTTP POST request to Target edge servers to process the file. Here is a sample HTTP POST request for the file batch.txt using the curl command:
curl -X POST --data-binary @BATCH.TXT http://CLIENTCODE.tt.omtrdc.net/m2/ CLIENTCODE/v2/profile/batchUpdate
Where:
BATCH.TXT is the filename. CLIENTCODE is the Target client code.
If you don’t know your client code, in the Target UI click Setup > Implementation > Edit Mbox.js Settings. The client code is shown in the Client field.
Inspect the response.
v2 returns a profile-by-profile status and v1 returns only the overall status. The response includes a link to a different URL that has the profile-by-profile success message.
Example Response:
In case of an error, the response will contain success=false and a detailed message for the error.
A successful response will look like the following:
- success: The profile was updated. If the profile was not found, one was created with the values from the batch.
- error: The profile was not updated or created due to a failure, exception, or message loss.
- pending: The profile has not been updated or created yet.