Forecast Adjustment API

Document created by catherine.racette on Jul 6, 2017Last modified by catherine.racette on Aug 29, 2017
Version 13Show Document
  • View in full screen mode

 

Description

Forecast Adjustment API enables publishers to create, update and get Forecast Adjustments. This API supports the generic search for getting the Forecast Adjustment details with different criteria.

For more information about UAS Ad Forecaster Services, refer to Ad Forecaster Services (UAS) 

Methods

Method Path

HTTP Method

DescriptionLink to Definition
/adjustment/POSTThis API method will create only one Forecast Adjustment per request. This will be in transaction.Creating a Forecast Adjustment
/adjustment/{id}GETRetrieve the details of a specific Forecast Adjustment for requested Forecast Adjustment Id.Retrieving Details of a Forecast Adjustment
/adjustment/GET

Retrieve the list of Forecast Adjustments associated with your account.  

With this, you can apply supported dimensions by Forecast Adjustment, filters and sorting option to fetch list of Forecast Adjustments with   specific  set  of details according  to  your needs.

Find more details about how to use dimensions, sort and filters options  here .

Retrieving List of Forecast Adjustments
/adjustment/{id}PUT

The API method is exposed to update single Forecast Adjustment. This will be in transaction.

  1. This method will do full update. If the request does not contain value for an attribute then it will be 
    either set to NULL/default value. But if the parameter is mandatory then it will fail an no line item will be updated
  2. Client must ensure that it passing all the required attributes with required values.
Updating a Forecast Adjustment
/adjustment/{id}PATCH

The API method is exposed to perform partial update on an object. e.g. If we want to change the adjustmentValue of the Forecast Adjustment then use partial update.

NOTE :  It is different than PUT. In PUT full replacement of the Object takes place.

Patch a Forecast Adjustment
/adjustment/{id}DELETE

This API method is used for archiving the Forecast Adjustment.

Deleting a Forecast Adjustment   

Request Body

Parameter Name
Type
Required
Validations
Description
nameStringYes
  1. Name should be unique for your account.
  2. Name can be of maximum 255 characters.
Forecast Adjustment Name
descriptionStringNo

NA

Description of the Forecast Adjustment.
accountIdIntegerYes
  1. Account of publisher for which this Forecast Adjustment is created
Account of the Publisher
adjustmentTypeIntegerYes
  1. Should be valid and exist in the system
  2. adjustmentType is mandatory

Type of the adjustment. Currently we have two types:

IdAdjustment Type
1Percentage
2Total Number
statusIntegerYes
  1. Status should be valid and exist
  2. Default is "Active" if the forecast adjustment is created successfully along with the "Hint" in the Shift Forward system. The status will be "Failed" if the adjustment is created but the corresponding "Hint" is not created in the Shift Forward system.

Status of the Forecast Adjustment.

Following status are supported for the Forecast Adjustment:

IdName
5Failed
6Archived
7Active
adjustmentValueIntegerYes
  1. Should be a valid Integer.
  2. For the adjustment of type percentage the adjustmentValue should be in the range -100 and 200 both inclusive.
  3. For the adjustment of type number the adjustmentValue can be any integer.
The Adjustment Value
startDateDateYes
  1. Date and Time should be greater than current date and less than End Date.
  2. Date and Time must be in  yyyy-MM-dd'T'HH:mm:ss 
    E.g. 2016-06-01T00:00:00
Start Date for the Adjustment.
endDateDateYes
  1. Date and Time should be greater than current date and greater than start Date.
  2. Date and Time must be in  yyyy-MM-dd'T'HH:mm:ss 
    E.g. 2016-06-01T00:00:00
End Date for the Adjustment.
targetingMapYes
  1. We have two targets supported for the Adjustment - Inventory and AdSize.
  2. The target values (inventory and ad size ids) must be valid and exist in the system.

Targets for which the Adjustment is created.

Following is an example of the targeting:

"targeting": {
        "inventory": {
            "targets": [{
                "targetValue": 1000091,
                "exclude": false,
                "targetLevel": 2
            }]
        }
    }
existingAdUnitIdIntegerNo
  1. The adunit must be valid and exist in the system.
  2. The adunit must be different from the list of adunits mentioned in the targeting list.
The Reference Ad Unit. This serves as the reference for a ad unit for which forecast has to be adjusted. This is typically done for a new inventory.

Examples For Supported Operations

Creating a Forecast Adjustment 

 

 The Create operation will create an Line Item in the system.

URL

http://api.pubmatic.com/v1/forecaster/forecast-apiadjustment/ 

HTTP Method

POST

Sample Request

Post Body:
{
"name": "Test Adjustment",
"description": "Test Description",
"accountId": 118385,
"adjustmentType": {
"id": 1
},
"status": {
"id": 7
},
"adjustmentValue": 50,
"startDate": "2017-06-19T00:00:00",
"endDate": "2017-06-19T23:59:59",
"timeZoneId": 12,
"targeting": {
"inventory": {
"targets": [
{
"targetValue": 1000091,
"exclude": false,
"targetLevel": 2
}
]
}
},
"existingAdUnitId": 1000090
}
Sample Response

Response:

{
"id": 2001,
"name": "Test Adjustment",
"description": "Test Description",
"accountId": 118385,
"hintId": "2001",
"adjustmentType": {
"id": 1,
"name": "Percentage"
},
"status": {
"id": 7,
"name": "Active",
"description": null,
"url": null
},
"adjustmentValue": 50,
"startDate": "2017-06-19T00:00:00",
"endDate": "2017-06-19T23:59:59",
"timeZoneId": 12,
"userId": 18280,
"targeting": {
"inventory": {
"entity": null,
"targets": [
{
"targetValue": 1000091,
"exclude": false,
"targetLevel": 2,
"url": null,
"id": null,
"name": "AdUnit_A5_2"
}
],
"url": null,
"id": null,
"name": null
}
},
"existingAdUnitId": 1000090,
"createdAt": "2017-06-27 15:11:47",
"updatedAt": "2017-06-27 15:11:50"
}

 

Updating a Forecast Adjustment 

URL

https://api.pubmatic.com/v1/forecaster/adjustment/{adjustmentid}

HTTP Method

PUT

Sample Request

Post Body:

{
"name": "Test Adjustment - Update",
"description": "Test Description",
"accountId": 118385,
"adjustmentType": {
"id": 1
},
"status": {
"id": 7
},
"adjustmentValue": 50,
"startDate": "2017-06-19T00:00:00",
"endDate": "2017-06-19T23:59:59",
"timeZoneId": 12,
"targeting": {
"inventory": {
"targets": [
{
"targetValue": 1000091,
"exclude": false,
"targetLevel": 2
}
]
}
},
"existingAdUnitId": 1000090
}
 
Sample Response

Response:

{
"id": 2001,
"name": "Test Adjustment - Update",
"description": "Test Description",
"accountId": 118385,
"hintId": "2001",
"adjustmentType": {
"id": 1,
"name": "Percentage"
},
"status": {
"id": 7,
"name": "Active",
"description": null,
"url": null
},
"adjustmentValue": 50,
"startDate": "2017-06-19T00:00:00",
"endDate": "2017-06-19T23:59:59",
"timeZoneId": 12,
"userId": 18280,
"targeting": {
"inventory": {
"entity": null,
"targets": [
{
"targetValue": 1000091,
"exclude": false,
"targetLevel": 2,
"url": null,
"id": null,
"name": "AdUnit_A5_2"
}
],
"url": null,
"id": null,
"name": null
}
},
"existingAdUnitId": 1000090,
"createdAt": "2017-06-27 15:11:47",
"updatedAt": "2017-06-27 15:11:50"
}

 

Retrieving Details of a Forecast Adjustment 

URL

https://api.pubmatic.com/v1/forecaster/adjustment/{adjustmentid} 

HTTP Method

GET

Sample Requesthttps://api.pubmatic.com/v1/forecaster/adjustment/2001 
Sample Response

Response:

{
"id": 2001,
"name": "Test Adjustment",
"description": "Test Description",
"accountId": 118385,
"hintId": "2001",
"adjustmentType": {
"id": 1,
"name": "Percentage"
},
"status": {
"id": 7,
"name": "Active",
"description": null,
"url": null
},
"adjustmentValue": 50,
"startDate": "2017-06-19T00:00:00",
"endDate": "2017-06-19T23:59:59",
"timeZoneId": 12,
"userId": 18280,
"targeting": {
"inventory": {
"entity": null,
"targets": [
{
"targetValue": 1000091,
"exclude": false,
"targetLevel": 2,
"url": null,
"id": null,
"name": "AdUnit_A5_2"
}
],
"url": null,
"id": null,
"name": null
}
},
"existingAdUnitId": 1000090,
"createdAt": "2017-06-27 15:11:47",
"updatedAt": "2017-06-27 15:11:50"
}

 

Retrieving List of Forecast Adjustments 

URL

https://api.pubmatic.com/v1/forecaster/adjustment/ 

HTTP Method

GET

Sample Requesthttps://api.pubmatic.com/v1/forecaster/adjustment/ 
Sample Response

It will return all adjustments associated with your account.

 

Generic Search 

URL

https://api.pubmatic.com/v1/forecaster/adjustment? dimensions=id,name,status&sort=id&filters=id eq <specify adjustment id>

HTTP Method

GET

Sample Requesthttps://api.pubmatic.com/v1/forecaster/adjustment ?dimensions=id,name,status&sort=id&filters=id eq 2001
Sample Response

It will return all adjustments satisfying the given conditions associated with your account.

 

Patch a Forecast Adjustment 

URL

https://api.pubmatic.com/v1/forecaster/adjustment/{adjustmentid} 

HTTP Method

PATCH

Sample Request

Post Body:

{
"name": "Test Adjustment - Patch"
}
Sample Response
{
"id": 2001,
"name": "Test Adjustment - Patch",
"description": "Test Description",
"accountId": 118385,
"hintId": "2001",
"adjustmentType": {
"id": 1,
"name": "Percentage"
},
"status": {
"id": 7,
"name": "Active",
"description": null,
"url": null
},
"adjustmentValue": 50,
"startDate": "2017-06-19T00:00:00",
"endDate": "2017-06-19T23:59:59",
"timeZoneId": 12,
"userId": 18280,
"targeting": {
"inventory": {
"entity": null,
"targets": [
{
"targetValue": 1000091,
"exclude": false,
"targetLevel": 2,
"url": null,
"id": null,
"name": "AdUnit_A5_2"
}
],
"url": null,
"id": null,
"name": null
}
},
"existingAdUnitId": 1000090,
"createdAt": "2017-06-27 15:11:47",
"updatedAt": "2017-06-27 15:11:50"
}

 

Deleting a Forecast Adjustment 

URL

https://api.pubmatic.com/v1/forecaster/adjustment/{adjustmentid} 

HTTP Method

DELETE

Sample Requesthttps://api.pubmatic.com/v1/forecaster/adjustment/ 
Sample Response

Returns true if archival is successful. False, otherwise

 

Error Codes For Line Item

Sr. NoError CodesDescription

1

PH_ERROR_INTERNAL_CONFIGURATION

This error message occurs in following cases -

  1. When we have a communication or Error response from Shift Forward system.
2PH_MISSING_OR_INVALID_PARAMETER

This error message occurs in following cases -

  1. timeZoneId is null / invalid
  2. status is null
  3. name is null / empty
  4. startDate is null
  5. endDate is null
  6. adjustmentType is null / invalid
  7. adjustmentValue is null
  8. accountId is null
  9. existingAdUnitId is invalid
  10. targeting is null / empty
  11. targeting adUnit/s is/are null / invalid
  12. targeting adSize/s is/are null / invalid
3PH_PARAMETER_VALUE_TOO_LARGE

This error message occurs in following cases -

  1. name length is larger than 255
4PH_DUPLICATE_NAME

This error message occurs in following cases -

  1. name is duplicate at account level
5PH_ENTITY_RANGE_INCLUSIVE

This error message occurs in following cases -

  1. adjustmentValue is less than -100 or greater than 200 in case of adjustment type Percentage
6PH_FROM_DATE_SHOULD_BE_LESS_THAN_OR_EQUAL_TO_TO_DATE_MSG

This error message occurs in following cases -

  1. If startDate is greater than endDate
7PH_ADUNIT_TO_COPY_PRESENT_IN_TARGETING_MSG

This error message occurs in following cases -

  1. If the existingAdUnitId is duplicate from the targeting Ad Units.
8PH_OVERLAPPING_ADJUSTMENTS_MSG

This error message occurs in following cases -

  1. If there is any overlapping adjustment

 

 

Version 3

Attachments

    Outcomes