Taxonomy Partner Permissions API

If you are a DMP partner or data provider, you can use the taxonomy partner permissions API to whitelist (share) or blacklist (withhold) your first-party categories and inventory numbers with another partner. The partner receiving the whitelisted categories will then be able to view and select them from their taxonomy tree when they log in to the Oracle Data Cloud platform just as the DMP client owning the category would. You can also use this API to view the first-party categories in your private taxonomy that have been whitelisted or blacklisted to other partners.

Taxonomy permissioning, along with audience sharing, facilitates the second-party marketplace in the Oracle Data Cloud platform. While audience sharing enables you to share a single audience, taxonomy permissioning enables you to share category-level information with your trusted partners.

Note: Users no longer create campaigns in the Oracle Data Cloud platform UI. The campaign workflow is now part of the audience workflow. The platform still uses campaigns to manage audience data delivery however. They are created automatically when a UI user delivers an audience. In the APIs, you create and use campaigns as before.

In this topic  

Explore the API

The embedded I/O doc below enables you to explore the API. The I/O  doc explains the parameters for each method and provides templates for your calls. You cannot make live API calls from the tool, however.

Open the link below in a new tab to see the I/O doc in a three-pane format.

taxonomypermissioning.docs.apiary.io/

For help with this API, contact My Oracle Support (MOS).

Service URI

The URI for the taxonomy partner permissions API is:

taxonomy.bluekai.com/taxonomy/partnerPermissions

Related API calls

Here are the API calls you will typically make before you use the taxonomy partner permissions API:

Before taxonomy partner permissions API Use case
Categories API Add first-party categories to your private taxonomy.
Rules API Create classification rules that map the user data collected from your site with your categories.
Categories API View first-party categories that you can share with DMP clients and partners.

Here are the API calls you will typically make after you use the taxonomy partner permissions API:

After taxonomy partner permissions API Use case
Audiences API Receive categories from DMP clients that are to be optimized or modeled.

Schema

The URI for the taxonomy partner permissions API schema is:

taxonomy.bluekai.com/taxonomy/partnerPermission.schema

{
  "type" : "object",
  "$schema" : "https://json-schema.org/draft-04/schema#",
  "id" : "#partnerPermission",
  "description" : "The details of a particular partner permission stored at Bluekai",
  "additionalProperties" : false,
  "properties" : {
    "id" : {
      "type" : "integer",
      "description" : "The ID of a partner permission [Read Only Field]",
      "minimum" : 1
    },
    "partner" : {
      "type" : "object",
      "description" : "The Partner of a partner permission",
      "javaType" : "com.oracle.bluekai.types.taxonomy.Partner",
      "properties" : {
        "id" : {
          "type" : "integer",
          "description" : "ID of a partner"
        },
        "name" : {
          "type" : "string",
          "description" : "Name of a partner",
          "minLength" : 1,
          "maxLength" : 255
        }
      }
    },
    "buyer" : {
      "type" : "array",
      "items" : {
        "$ref" : "#stub"
      }
    },
    "whitelistCategories" : {
      "type" : "array",
      "items" : {
        "type" : "integer"
      },
      "description" : "List of category ids that are whitelisted",
      "minItems" : 1
    },
    "blacklistCategories" : {
      "type" : "array",
      "items" : {
        "type" : "integer"
      },
      "description" : "List of category ids that are blacklisted",
      "minItems" : 1
    },
    "notes" : {
      "type" : "string",
      "description" : "Notes for a partner permission",
      "minLength" : 1
    },
    "permissionType" : {
      "enum" : [ "targetingAndAnalytics", "analytics" ],
      "description" : "Describes the taxonomy permission type",
      "default" : "targetingAndAnalytics"
    },
    "createdAt" : {
      "type" : "string",
      "format" : "date-time",
      "description" : "Creation date and time [Read Only Field]",
      "minLength" : 20,
      "maxLength" : 25
    },
    "updatedAt" : {
      "type" : "string",
      "format" : "date-time",
      "description" : "Update date and time [Read Only Field]",
      "minLength" : 20,
      "maxLength" : 25
    }
  },
  "required" : [ "partner", "buyer" ]
}

List permissions

To view all your taxonomy partner permissions make the following GET call:

taxonomy.bluekai.com/taxonomy/partnerPermissions?pid=yourPartnerID&bkuid=BKUID&bksig=BKSIG

The pid value is only needed if your user account is associated with multiple partner seats.

Sample list response:

{
  "items" : [ {
    "id" : 19795,
    "partner" : {
      "id" : 2208,
      "name" : "Example Partner"
    },
    "buyer" : [ {
      "id" : 2362,
      "name" : "Example Buyer 1"
    } ],
    "whitelistCategories" : [ 338800, 344778 ],
    "blacklistCategories" : [ 339307, 339298, 339301 ],
    "permissionType" : "targetingAndAnalytics",
    "createdAt" : "2016-05-24T17:57:22-05:00",
    "updatedAt" : "2016-06-03T16:01:07-05:00"
  }, {
    "id" : 19833,
    "partner" : {
      "id" : 2208,
      "name" : "Example Partner"
    },
    "buyer" : [ {
      "id" : 1392,
      "name" : "Example Buyer 2"
    } ],
    "whitelistCategories" : [ 287744 ],
    "permissionType" : "analytics",
    "createdAt" : "2016-06-03T17:13:15-05:00",
    "updatedAt" : "2016-06-03T17:13:15-05:00"
  }, {
    "id" : 19859,
    "partner" : {
      "id" : 2208,
      "name" : "Example Partner"
    },
    "buyer" : [ {
      "id" : 1739,
      "name" : "Example Buyer 3"
    } ],
    "whitelistCategories" : [ 287744 ],
    "blacklistCategories" : [ 338799 ],
    "permissionType" : "analytics",
    "createdAt" : "2016-06-08T15:55:27-05:00",
    "updatedAt" : "2016-06-08T18:33:00-05:00"
  }, {
    "id" : 20154,
    "partner" : {
      "id" : 2208,
      "name" : "Example Partner"
    },
    "buyer" : [ {
      "id" : 486,
      "name" : "Example Buyer 4"
    } ],
    "whitelistCategories" : [ 287744 ],
    "permissionType" : "targetingAndAnalytics",
    "createdAt" : "2016-08-19T16:04:06-05:00",
    "updatedAt" : "2016-08-19T16:04:06-05:00"
  } ],
  "totalResults" : 4,
  "offset" : 0,
  "count" : 4,
  "hasMore" : false
}

Create permissions

To create taxonomy partner permissions, make a POST call and include your partner ID, the buyer ID, and a list of one or more whitelisted or blacklisted first-party categories in the body:

Sample POST request

taxonomy.bluekai.com/taxonomy/partnerPermissions?pid=yourPartnerID&bkuid=BKUID&bksig=BKSIG

The pid value is only needed if your user account is associated with multiple partner seats.

Sample body 

{
	"partner": {
		"id": 2208
	},
	"buyer": [{
		"id": 2362
	}],
	"whitelistCategories": [828103],
	"permissionType": "targetingAndAnalytics"
}

Note:Only one taxonomy permission is allowed per buyer. Once you create a taxonomy permission (a POST call), you must update (PUT calls) to whitelist or blacklist additional categories for the same buyer.

GET, POST, and PUT response summary

The taxonomy partner permissions API GET request returns the first-party categories that you have shared with DMP clients or partners. Here are the properties included for each shared first-party category:

Property Type Description
blacklistCategories array A list of comma-separated category IDs that have been blacklisted for the DMP client or data buyer
buyer array (Required) An array describing the DMP client or data buyer with whom you are sharing the first-party categories specified in whitelistCategories, including their ID and name
createdAt string A timestamp indicating when the taxonomy permission was created, such as 2017-03-10T08:03:13-05:00
id integer The unique ID assigned to the taxonomy partner permission
notes string A user-specified summary of the taxonomy partner permission
partner object (Required) An object describing the partner seat, including the ID and name. If you have multiple partner seats associated with your user account, you can include the pid value in your request and specify the ID of the desired partner seat.
permissionType enum The type of taxonomy permission, which can be targetingAndAnalytics (the default) or analytics
updatedAt string A timestamp indicating when the taxonomy permission was last modified
whitelistCategories array A list of comma-separated category IDs that have been whitelisted for the DMP client or data buyer

Learn more

Introduction to the Oracle Data Cloud APIs

Using taxonomy permissions to share your data