IP Range Targeting (UAS)

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

Description

Use the IP Range Targeting API to target the IP Addresses for line items.

Important Note:

  1. This API will not validate IP addresses, therefore make sure you are passing the correct IP ranges.
  2. You can target the IP Address range and the API does not check for overlapping IP addresses within the provided set of IP ranges.

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/iprangesPOSTAdd/Update/Remove IP Range Targeting for the Line ItemConfigure IP Targeting Ranges
/lineitems/{lineItemId}/targets/iprangesGETRetrieve IP Range Details for a Line ItemRetrieve Targeted IP Range for a Line Item

 

Configure IP Targeting Ranges

 

Overview

This API enables you to add, update or remove IP Range 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

This API accepts array of target objects, where each object must contain following attributes

                               

Parameter NameTypeRequiredValidationsDescriptions
targetLevelNumericYes

Should not be null.

Should not be empty.

IP Range has only a single target level, therefore always pass 1.

               
Target LevelTargetDescription 
1IP RangeIP Range Targeting 
targetValueNumeric

Yes

Should not be null.

Should not be empty.

Target Value will contain Start IP Address and End IP Address actual values.

    
{
    "from": "172.16.4.29",
    "to": "172.16.4.35"
}

The following are supported data types:

             
Target TypeTarget Value Data TypeReference/Actual Value
IP Range TypeObject

Actual Values of Start IP Address and End IP Address.

NOTE:

If you want to target for a single IP address, e.g., 172.16.4.29, the input should be as follows:

    
{
    "from": "172.16.4.29",
    "to": "172.16.4.29"  /*From & TO values are same*/
}
 
excludeBooleanYes

Default will be false.

Valid values can be true or false.

This value indicates whether the IP Range is to be included / excluded while targeting the Line Item.

Sample Request URL

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

Sample Request JSON

     

{
    "targets": [
        {
            "targetValue": {
                "from": "172.16.4.29",
                "to": "172.16.4.35"
            },
            "targetLevel": 1,
            "exclude": false
        },
        {
            "targetValue": {
                "from": "172.16.4.50",
                "to": "172.16.4.50"
            },
            "targetLevel": 1,
            "exclude": true
        }
    ]
}

Sample Request JSON: To Remove all IP Range Targeting for a Line Item

    

{
    "targets": [ ]
}

 

Response

Sample Response JSON

    

{
    "entity": {
        "id": {targetid associated with lineitem},      
        "isPreset": 0
    },
    "targets": [
        {
            "targetValue": {
                "from": "172.16.4.29",
                "to": "172.16.4.35"
            },
            "exclude": false,
            "targetLevel": 1
        },
        {
            "targetValue": {
                "from": "172.16.4.50",
                "to": "172.16.4.50"
            },
            "exclude": true,
            "targetLevel": 1
        }
    ]
}

Retrieve Targeted IP Range for a Line Item

 

Overview

This API enables you to retrieve IP Range targeting for a Line Item.

Request

           

URIHTTP Method

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

GET

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

This API accepts array of target objects, where each object must contain following attributes

                               

Parameter NameTypeRequiredValidationsDescriptions
targetLevelNumericYes

Should not be null.

Should not be empty.

IP Range has only a single target level, therefore always pass 1.

               
Target LevelTargetDescription 
1IP RangeIP Range Targeting 
targetValueNumeric

Yes

Should not be null.

Should not be empty.

Target Value will contain Start IP Address and End IP Address actual values.

    
{
    "from": "172.16.4.29",
    "to": "172.16.4.35"
}

The following are supported data types:

             
Target TypeTarget Value Data TypeReference/Actual Value
IP Range TypeObject

Actual Values of Start IP Address and End IP Address.

NOTE:

If you want to target for a single IP address, e.g., 172.16.4.29, the input should be as follows:

    
{
    "from": "172.16.4.29",
    "to": "172.16.4.29"  /*From & TO values are same*/
}
 
excludeBooleanYes

Default will be false.

Valid values can be true or false.

This value indicates whether the IP Range is to be included / excluded while targeting the Line Item.

Sample Request URL

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

Response

Sample Response JSON

    



{
    "targets": [
        {
            "targetValue": {
                "from": "172.16.4.29",
                "to": "172.16.4.35"
            },
            "exclude": false
        },
        {
            "targetValue": {
                "from": "172.16.4.50",
                "to": "172.16.4.50"
            },
            "exclude": true
        }
    ]
}





 

Error Codes for IP Range Targeting

                                       

Sr. NoError CodesError MessageDescription
1.PH_ACCESS_DENIEDAccess DeniedWhen the provided lineitemid does not exist or you do not have access to the line item to perform the edit operation.
2.PH_MISSING_OR_INVALID_PARAMETERMissing or Invalid Target ValueWhen any target object contains NULL or is an empty target value
3.PH_MISSING_OR_INVALID_PARAMETERMissing or Invalid entity id [1442]When an Invalid Line Item Id is provided in the request.
4.PH_FROM_ENTITY_GREATER_THAN_TO_ENTITYFrom IP must be less than or equal to IPWhen From/To contains an Invalid IP Address
5.PH_DUPLICATE_ENTRIES_FOUNDDuplicate IP Range (e.g., 172.16.4.50 - 172.16.4.50)When a duplicate IP Address range is input.

 

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.1

Attachments

    Outcomes