Inventory Targeting (UAS)

Document created by pubmatic-archivist on Mar 27, 2017Last modified by catherine.racette on Aug 29, 2017
Version 7Show Document
  • View in full screen mode

Description

Use the Inventory Targeting API to deliver the line items on individual Ad Units or all Ad Units i.e., Run of Network.

 

Important Note:

  1. This API will not actually validate targetValue  ( i.e. id's for respective targeting ) provided in the POST call.  User should retrieve the valid target details using a related Common API and provide id's for respective targeting.
  2. User should make sure that same targetValues are not getting included / excluded at same time for same line item.

 This API must be called after creating/updating Line Item successfully since it require lineitemId during targeting.

For more information about UAS Line Item Targeting Services, refer to Line Item Targeting Services (UAS)

Supported Operations

                     

Method PathHTTP MethodDescriptionLink to Definition
/lineitems/{lineItemId}/targets/inventoriesPOSTAdd/Remove/Update Inventory Targeting for a Line ItemConfigure Inventories
/lineitems/{lineItemid}/targets/inventoriesGETRetrieve the details of a specific Ad Unit for the requested Ad Unit IDRetrieve Targeted Inventories for Line Item

 

Configure Inventories

Overview

This API enables you to add, update or remove inventories.

Request

           

Request Headers

                        

Header nameType ValueRequiredDescription
Content-TypeStringapplication/jsonYesMedia type for request.
pubTokenString${access_token}Yes

Publisher Token to authenticate and authorize the user calling the Unified Ad Server API. Send the access token generated for authentication at the place of ${access_token} in the request.

 

For more information about access tokens, refer to Getting Started with PubMatic APIs.

Request Body Parameters

                               

Parameter NameTypeRequiredValidationsDescriptions
targetLevelNumericYes

Should not be null.

Should not be empty

Target Level  represents the type of inventory you are trying to target.

The following are valid Target Levels for Inventory Targeting:

                       
Target LevelTargetDescription
-1Run of NetworkLine Item to be targeted for all ad Units. You do not have to select all Ad Units during targeting in this case.
1Ad Unit GroupImportant Note: Targeting on Ad Unit Group is not supported as of this date. This Target Level is reserved for future reference.
2Ad Unit

Target the specific one or more Ad Units on the line item. You can retrieve the available list of Ad Units for your account using the Ad Unit API.

You cannot associate archived adUnits with target levels. If an adUnit is archived after it is associated with the lineitem, validation of such a associated adUnits is not done.

targetValueNumeric Yes

Yes

Should not be null.

Should not be empty.

TargetValue will contain reference value.

                       
Target TypeTarget Value Data TypeReference/Actual Value
Run of NetworkNot Applicable

Important note: You don't have to pass the targetValue during targeting if wish to run Line Item on Run of Inventory.

This will be not honor the exclude parameter and always include Run of Network on Line Item Level.

Ad Unit GroupNumeric
Important Note: Targeting on Ad Unit group is not supported as on date. This Target Level reserved for future reference.
Ad UnitNumericReference Value. id attribute from the response returned by the Ad Unit API.
excludeBooleanYes

Default will be false.

Valid values can be true or false

This value indicates whether the Inventory to be included / excluded while targeting the Line Item

NOTE :

  1. This is not applicable if you are selecting Run of Network Inventory.
  2. In this case PubMatic Ad Server will not map any Ad Unit / Ad Unit Group to underlying Line Item
  3. Hence, target value will be ignored if you are selecting Run on Network inventory.

Sample Request URL

https://api.pubmatic.com/v1/uas/lineitems/{lineItemId}/targets/inventories/ 

Sample Request JSON: Target Line Item on Specific Ad Units

{
    "targets": [{
        "targetLevel": 2,
        "exclude": false,
        "targetValue": 298,
        "name": "AdUnit_ATF_US_News"
    }, {
        "targetLevel": 2,
        "exclude": false,
        "targetValue": 13,
        "name": "AdUnit_Main_Page"
    }]
}

Sample Request JSON: Target the Line Item to Run on Network

{
     "targets": [
            {
              "targetLevel": -1
            }
       ]
}

Response

Sample Response JSON: Target Line Item on Specific Ad Units

    

{
    "entity": {
        "account": {
            "id": { Your account identifier },
            "name": "{ Your account name }"
        },
        "id": {targetid associated with lineitem},
        "isPreset": 0
    },
    "targets": [{
        "targetValue": 298,
        "exclude": false,
        "targetLevel": 2,
        "name": "AdUnit_ATF_US_News"
    }, {
        "targetValue": 13,
        "exclude": false,
        "targetLevel": 2,
        "name": "AdUnit_Main_Page"
    }]
}

Sample Response JSON: Target the Line Item to Run on Network

    

{
     "entity": {
        "account": {
            "id": { Your account identifier },
            "name": "{ Your account name }"
        },
        "id": {targetid associated with lineitem},
        "isPreset": 0
    },
    "targets": [{
        "exclude": false,
        "targetLevel": -1,
        "name": "Run of Network"
    }]
}

Retrieve Targeted Inventories for Line Item

 

Overview

This API enables you to retrieve targeted inventories for a line item.

Request

           

Request Headers

                        

Header nameType ValueRequiredDescription
Content-TypeStringapplication/jsonYesMedia type for request.
pubTokenString${access_token}Yes

Publisher Token to authenticate and authorize the user calling the Unified Ad Server API. Send the access token generated for authentication at the place of ${access_token} in the request.

 

For more information about access tokens, refer to Getting Started with PubMatic APIs.

Request Body Parameters

                               

Parameter NameTypeRequiredValidationsDescriptions
targetLevelNumericYes

Should not be null.

Should not be empty

Target Level  represents the type of inventory you are trying to target.

The following are valid Target Levels for Inventory Targeting:

                       
Target LevelTargetDescription
-1Run of NetworkLine Item to be targeted for all ad Units. You do not have to select all Ad Units during targeting in this case.
1Ad Unit GroupImportant Note: Targeting on Ad Unit Group is not supported as of this date. This Target Level is reserved for future reference.
2Ad Unit

Target the specific one or more Ad Units on the line item. You can retrieve the available list of Ad Units for your account using the Ad Unit API.

You cannot associate archived adUnits with target levels. If an adUnit is archived after it is associated with the lineitem, validation of such a associated adUnits is not done.

targetValueNumeric Yes

Yes

Should not be null.

Should not be empty.

TargetValue will contain reference value.

                       
Target TypeTarget Value Data TypeReference/Actual Value
Run of NetworkNot Applicable

Important note: You don't have to pass the targetValue during targeting if wish to run Line Item on Run of Inventory.

This will be not honor the exclude parameter and always include Run of Network on Line Item Level.

Ad Unit GroupNumeric
Important Note: Targeting on Ad Unit group is not supported as on date. This Target Level reserved for future reference.
Ad UnitNumericReference Value. id attribute from the response returned by the Ad Unit API.
excludeBooleanYes

Default will be false.

Valid values can be true or false

This value indicates whether the Inventory to be included / excluded while targeting the Line Item

NOTE :

  1. This is not applicable if you are selecting Run of Network Inventory.
  2. In this case PubMatic Ad Server will not map any Ad Unit / Ad Unit Group to underlying Line Item
  3. Hence, target value will be ignored if you are selecting Run on Network inventory.

Sample Request URL

https://api.pubmatic.com/v1/uas/lineitems/{lineItemId}/targets/inventories/ 

Sample Request JSON

    

{
    "targets": [{
        "targetValue": 298,
        "exclude": false,
        "targetLevel": 2,
        "name": "AdUnit_ATF_US_News"
    }, {
        "targetValue": 13,
        "exclude": false,
        "targetLevel": 2,
        "name": "AdUnit_Main_Page"
    }]
}

 

Sample Response JSON

    

{
     "entity": {
        "account": {
            "id": { Your account identifier },
            "name": "{ Your account name }"
        },
        "id": {targetid associated with lineitem},
        "isPreset": 0
    },
    "targets": [{
        "exclude": false,
        "targetLevel": -1,
        "name": "Run of Network"
    }]
}

Sample Response JSON: For Line Item Targeted on Run of Network

    

{
    "targets": [{
        "exclude": false,
        "targetLevel": -1,
        "name": "Run of Network"
    }]
}

Error Codes For Inventory Targeting

Error codes will be displayed with row information. Row indicates the order of the target object in the request

                           
Sr. NoError CodesError MessageDescription
1PH_MISSING_OR_INVALID_PARAMETERMissing or Invalid Target Value

When any target object contains NULL or empty target value.

When you are trying to set Run of Network and exclude few Ad Units.

When user tries to set the targetLevel = 1 for Ad Unit Group.

2PH_DUPLICATE_ENTRIES_FOUND

Duplicate Targets targetValue - id

When same Ad unit is duplicated during the configuration of the Line Item at any level.
3.PH_ATTEMPT_TO_ASSOCIATE_WITH_UNSUPPORTED_STATUS_ENTITYAdunit to be associated is in archived status.This error occurs when you select an archived adUnit for association.

 

Unified Ad Server References

Common Request Query Parameters for Web Services

Supported Operations for Filters

HTTP Status Codes

Unified Ad Server Specific Error Codes

 

Attachments

    Outcomes