Holistic Optimization API (UAS)

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

Description

The Unified Ad Server supports following holistic optimization settings to enable it on an account for cross-channel optimization between guaranteed and programmatic. You can set the following levels for your account based on risk factors.

For more information about UAS Account & Admin Services APIs, refer to Account & Admin Services (UAS) 

Choose from one of the following five levels:

                                   

Description/LevelsLevel 1Level 2Level 3Level 4Level 5
Programmatic demand competes withNoneLower or equal priority guaranteed line items.All guaranteed line items (except Sponsorship).All guaranteed line items (except Sponsorship).All guaranteed line items (except Sponsorship).
Delivery impact on higher priority line items (Risk Percentage):NoneNoneUp to 5%Up to 10% Up to 20%
Potential monthly revenue upside:NoneLowMediumHighMaximum

Whenever programmatic demand competes with guaranteed line items, minimum condition to be satisfied is that eCPM of programmatic demand (RTB/PMP) should be more than competing guaranteed line items.

Supported Services

Service Name: Holistic Optimization Setting 

holisticoptimatizationsettings/

                     

Method PathHTTP Method TypeDescriptionLink to Definition
/holisticoptimizationsettings/{id}GETRetrieves the optimization setting details using the Setting Id.Retrieve Details of a Setting
/holisticoptimizationsettings/GET

Lists all the holistic optimization settings in the system.

In the query, you can also apply supported dimensions, filters and sorting options to retrieve a list with a specific set of details according to your requirements.

Retrieving a List of Supported Settings

 

 

Retrieve Details of a Setting

 

Overview

This API enables you to retrieve the details of an individual setting.

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.

 

Sample Request URL

https://api.pubmatic.com/v1/uas/holisticoptimizationsettings/5 

Response

Response Body

                            

Parameter Name/DimensionTypeDescription
idNumericPubMatic Identifier for the setting
nameStringName for respective the setting
descriptionStringDescription for the setting
riskPercentageNumericRisk Percentage associated with the setting.

Sample Response JSON

    

{
   "id": 5,
   "name": "Level 5",
   "description": "All guaranteed line items (except Sponsorship).",
   "riskPercentage": 20
}
 

Retrieving a List of Supported Settings

 

Overview

This API enables you to retrieve a list of supported optimization settings. In the query, you can also apply supported dimensions, filters and sorting options to retrieve a list of supported settings with a specific set of details according to your requirements.

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.

 

Sample Request URL

https://api.pubmatic.com/v1/uas/holisticoptimizationsettings?dimensions=name,description&filters=id eq 1

 

Response

Response Body

                            

Parameter Name/DimensionTypeDescription
idNumericPubMatic Identifier for the setting
nameStringName for respective the setting
descriptionStringDescription for the setting
riskPercentageNumericRisk Percentage associated with the setting.

Sample Response JSON

Response based on sample URL, to find those whose id = 1.

    

{
  "metaData": {
    "startIndex": 1,
    "totalRecords": 1,
    "pageNumber": 1,
    "endIndex": 1,
    "pageSize": 100
  },
  "items": [
    {
     "id": 5,
     "name": "Level 5",
     "description": "All guaranteed line items (except Sponsorship).",
     "riskPercentage": 20
    }
  ]
}
 

Error Codes for Holistic Optimization Settings

 

 Error Codes for Holistic Optimization Settings

               

Sr. No

Error Codes

Error Message

Description

1.

MISSING_OR_INVALID_PARAMETER

Missing or Invalid entity id [ < Setting Id provided by you > ]

If you requested details for allowed holistic optimization settings with id which is not exists or invalid

 

 

 

Unified Ad Server References

Common Request Query Parameters for Web Services

Supported Operations for Filters

HTTP Status Codes

Unified Ad Server Specific Error Codes

 

Version 0.2

Attachments

    Outcomes