Page tree


Before using PubMatic APIs, first generate the API Token. For more information, refer to  Getting Started with PubMatic APIs .  

This API lets you configure settings for holistic optimization at an account level to control cross-channel optimization for inventory. You can find the supported holistic optimization settings details using the Holistic Optimization API.

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

Supported Operations

Service Name: /accountholisticoptimizationsettingassociations/

Method PathHTTP Method TypeDescriptionLink to Definition

/accountholisticoptimizationsettingassociations/accounts/{accountId}/configure/
accounts/{accountId}
GETRetrieves the details of account level optimization. Setting configured for account id.Retrieve Account Level Optimization Setting
/accountholisticoptimizationsettingassociationsGETRetrieves the Holistic Optimization Settings for all accounts for which you are authorized access.Retrieve Settings for All Accounts
/accountholisticoptimizationsettingassociations/accounts/{accountId}/configurePOSTConfigure the Optimization Setting at an Account LevelConfigure Holistic Optimization Setting for an Account


Retrieve Account Level Optimization Setting

This API lets you retrieve the details of account level optimization settings configured for an account ID.

Request


Request Headers

Header nameType ValueRequiredDescription
Content-TypeStringapplication/jsonYesMedia type for request.
AuthorizationStringBearer ${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/accountholisticoptimizationsettingassociations/accounts/1

Response

Sample Response JSON

[{
     "account": {
          "id": 118385,
          "url": "http://$URI_PREFIX/phoenix/accounts/118385"
     },
     "holisticOptimizationSetting": {
          "id": 5,
          "name": "Optimize for revenue- high risk.",
          "url": "http://$URI_PREFIX/phoenix/holisticoptimizationsettings/5"
     },
     "riskPercentage": 5,
     "heldPeriod": 14,
     "trackerMethodForPacing": true
}]‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

 

Retrieve Settings for All Accounts

This API lets you retrieve the Holistic Optimization Setting for all accounts for which you are authorized to access. In the query, you can also apply supported dimensions, filters and sorting options to retrieve a list of Ad Units with a specific set of details according to your requirements. Using this API, you can apply dimensions, filter criteria and sorting option to retrieve a list of records.

See Common Request Query Parameters for more information about using dimensions, filters and sorting.

Request



Request Headers

Header nameType ValueRequiredDescription
Content-TypeStringapplication/jsonYesMedia type for request.
AuthorizationStringBearer ${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/accountholisticoptimizationsettingassociations

Response

Sample Response JSON

{
     "metaData": {
          "startIndex": 1,
          "totalRecords": 2,
          "pageNumber": 1,
          "endIndex": 2,
          "pageSize": 100
     },
     "items": [{
          "account": {
               "id": 118385,
               "url": "http://$URI_PREFIX/phoenix/accounts/118385"
          },
          "holisticOptimizationSetting": {
               "id": 4,
               "name": "Optimize for revenue- medium risk.",
               "url": "http://$URI_PREFIX/phoenix/holisticoptimizationsettings/4"
          },
          "riskPercentage": 12,
          "heldPeriod": 43,
          "trackerMethodForPacing": true
     }, {
          "account": {
               "id": 118386,
               "name": "PubMatic Inc.",
               "url": "http://$URI_PREFIX/phoenix/accounts/118385"
          },
          "holisticOptimizationSetting": {
               "id": 5,
               "name": "Optimize for revenue- high risk.",
               "url": "http://$URI_PREFIX/phoenix/holisticoptimizationsettings/5"
          },
          "riskPercentage": 12,
          "heldPeriod": 43,
          "trackerMethodForPacing": true
     }]
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

 

Configure Holistic Optimization Setting for an Account

This API lets you configure the Optimization setting at an account level.

Request



Request Headers

Header nameType ValueRequiredDescription
Content-TypeStringapplication/jsonYesMedia type for request.
AuthorizationStringBearer ${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
accountObjectYesValid Account (account should already exist in the system)Your account identifier
holisticOptimizationSettingObjectYesValid Setting (setting should already exist in the system)Setting supported by the Unified Ad Server. Details can be found in the Holistic Optimization API.
riskPercentageIntegerNoBetween 1 to 100.

This parameter is for future use only.

You will be use this parameter to customize risk percentage per your business needs.

Currently, you will receive the risk percentage as per respective holistic optimization setting. 

heldPeriodIntegerNoRange is 14 to 84

This is used to Hold the inventory in Forecast for configured number of days. You can find more details Here


Default value of this parameter is 14 days.


This parameter is used to store the period (in days) for which an inventory will be held by a lineItem.  It is maintained at account level.

trackerMethodForPacingBooleanNoEither true or false

Note: This is not yet in production. 


This configuration allows you to select the Line Item Goal Met condition.  


true: The Line Item Goal met or not will be determine by number of impressions actually fired (for example, Impressions / Paid Impressions ) on page after creative gets rendered.


false: The Line Item Goal met or not will determine by number of creative response UAS responded irrespective of whether creative rendered or not. (for example, Server Side Responses )  


Default value of this parameter is true.

This configuration is Account Level applicable for Guaranteed Line Items only.


Sample Request URL

https://api.pubmatic.com/v1/uas/accountholisticoptimizationsettingassociations

Sample Request JSON

{
   "account": {
     "id": 118385,
     "url": "http://$URI_PREFIX/phoenix/accounts/118385"
   },
   "holisticOptimizationSetting": {
     "id": 5,
     "name": "Optimize for revenue- high risk.",
     "url": "http://$URI_PREFIX/phoenix/holisticoptimizationsettings/5"
   },
   "riskPercentage": 20
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍


Response

Sample Response JSON

[{
     "account": {
          "id": 118385,
          "url": "http://$URI_PREFIX/phoenix/accounts/118385"
     },
     "holisticOptimizationSetting": {
          "id": 5,
          "name": "Optimize for revenue- high risk.",
          "url": "http://$URI_PREFIX/phoenix/holisticoptimizationsettings/5"
     },
     "heldPeriod": 14,
     "trackerMethodForPacing": true
}]‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍


Error Codes for Account Holistic Optimization Setting Association API

Sr. No

Error Codes

Description

1.

  PH_MISSING_OR_INVALID_PARAMETER

This error will occur when a mandatory parameter is missing or invalid in the request. 

This can occur for the following:

  • Account 

  • ‰ÛÜHolistic Optimization Setting

2.

PH_ENTITY_RANGE_INCLUSIVE

This error message occurs when riskPercentage value is not in the required range.


⇧ Top