Page tree


Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Anchor
top
top
Table of Contents
indent20px
stylenone



Warning

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

Targeting Services

Sr. NoTargetingsDescriptionSupported by Line Item / PresetSupported by Creative
1Inventory TargetingTarget to run on network, target on specific ad units or ad unit groups.

Yes

Yes
2Geography  TargetingTarget geographies by including/excluding Countries, Regions/States, Cities, DMAs, and or Zip/Postal Code.YesYes
3Zip TargetingTarget zip code.YesYes
4Hyper Local TargetingTarget on a given area using a central location coordinate and radius .YesYes
5Hyper Local Data Source TargetingTarget on different data sources to derive the user Geo Location coordinates.YesYes
6Browser TargetingTarget Browser by including/excluding browsers.YesNo
7Browser Language TargetingTarget browser language by including/excluding browser languages.YesYes
8Device Capability TargetingTarget Device capability by including/excluding device capabilities.YesNo
9OS TargetingTarget OS by including/excluding OS Name, OS Major Version and OS Minor Version.YesYes
10Device Type TargetingTarget Device Type by Including/Excluding Device Types.YesNo
11Device Manufacturer TargetingTarget for device based on their manufacturer by including/excluding device make.YesYes
12Connection Type TargetingTarget Connection Types by including/excluding connection types.YesNo
13IP Range TargetingTarget on Range of IP Addresses.YesYes
14UAS Custom Key Value Targeting APITarget on custom key value.YesYes
15. Audience TargetingTarget on various audience segments.YesNo


Info

Note: 

  1. On 'date' you have to list all targeting types in the request JSON. Add empty targets:[ ]  if that targeting type is not intended. If any targeting is missing in json it will give validation error. This is done for simplicity and consistency with configuration protocol.
  2. API is Transactional, which means that if there is a failure in any of the targeting nothing should be saved.
  3. At a granular level each targeting should contain only the three parameters {targetValue, targetLevel, exclude}.  If any extra parameter is preset in the post body during update / create is given, will result in an error.

Targeting Sample Example

Code Block
languagejs
linenumberstrue
collapsetrue
"targeting": {
        "audience": {},
        "browser": {
            "targets": [
                {
                    "targetValue": 7,
                    "exclude": false,
                    "targetLevel": 1,
                    "name": "Android Mobile"
                }
            ]
        },
        "browserLanguage": {
            "targets": [
                {
                    "targetValue": 3,
                    "exclude": false,
                    "targetLevel": 1,
                    "name": "Arabic"
                }
            ]
        },
        "connectionType": {
            "targets": [
                {
                    "targetValue": 1,
                    "exclude": false,
                    "targetLevel": 1,
                    "name": "Cellular"
                },
                {
                    "targetValue": 2,
                    "exclude": false,
                    "targetLevel": 1,
                    "name": "WiFi"
                }
            ]
        },
        "customKey": {},
        "device": {
            "targets": [
                {
                    "targetValue": 10692,
                    "exclude": false,
                    "targetLevel": 1,
                    "deviceTypeId": 3,
                    "deviceValue": "4geek",
                    "make": "4geek"
                }
            ]
        },
        "deviceCapability": {
            "targets": [
                {
                    "targetValue": 1,
                    "exclude": false,
                    "targetLevel": 1,
                    "deviceCapabilityId": 1,
                    "deviceCapabilityName": "Phone calls"
                }
            ]
        },
        "deviceType": {
            "targets": [
                {
                    "targetValue": 4,
                    "exclude": false,
                    "targetLevel": 1,
                    "deviceTypeId": 4,
                    "deviceType": "Tablet"
                }
            ]
        },
        "geo": {
            "targets": [
                {
                    "targetValue": 232,
                    "exclude": false,
                    "targetLevel": 1,
                    "countryCode": "US",
                    "name": "United States"
                }
            ]
        },
        "hyperLocal": {
            "targets": [
                {
                    "targetValue": {
                        "latitude": 18.5203062,
                        "longitude": 73.8543185,
                        "radius": 2,
                        "radiusInKm": 2,
                        "radiusUnit": "km"
                    },
                    "exclude": false
                }
            ]
        },
        "hyperLocalDataSource": {},
        "inventory": {
            "targets": [
                {
                    "targetValue": 10043201,
                    "exclude": false,
                    "targetLevel": 2,
                    "name": "AA_PH-6439_Test_AU"
                },
                {
                    "targetValue": 10043197,
                    "exclude": false,
                    "targetLevel": 2,
                    "name": "RobotAuto_AU_with_all_formats-01-30-2019 15-36-27vcjqx"
                },
                {
                    "targetValue": 10043198,
                    "exclude": false,
                    "targetLevel": 2,
                    "name": "RobotAuto_AU_with_all_formats-01-30-2019 15-38-20jmsui"
                }
            ]
        },
        "ipRange": {
            "targets": [
                {
                    "targetValue": {
                        "from": "1.1.1.1",
                        "to": "12.12.12.12"
                    },
                    "exclude": false,
                    "targetLevel": 1
                }
            ]
        },
        "os": {
            "targets": [
                {
                    "targetValue": 153,
                    "exclude": false,
                    "targetLevel": 1,
                    "osTypeId": 5,
                    "osName": "webOS"
                }
            ]
        },
        "zip": {}
    }

In order to update connectionType from 2 targets to single target in above targeting we need to pass complete targeting object with updated value for connectionType as follows:

Code Block
languagejs
linenumberstrue
collapsetrue
"targeting": {
        "audience": {},
        "browser": {
            "targets": [
                {
                    "targetValue": 7,
                    "exclude": false,
                    "targetLevel": 1,
                    "name": "Android Mobile"
                }
            ]
        },
        "browserLanguage": {
            "targets": [
                {
                    "targetValue": 3,
                    "exclude": false,
                    "targetLevel": 1,
                    "name": "Arabic"
                }
            ]
        },
        "connectionType": {
            "targets": [
                {
                    "targetValue": 1,
                    "exclude": false,
                    "targetLevel": 1,
                    "name": "Cellular"
                }
            ]
        },
        "customKey": {},
        "device": {
            "targets": [
                {
                    "targetValue": 10692,
                    "exclude": false,
                    "targetLevel": 1,
                    "deviceTypeId": 3,
                    "deviceValue": "4geek",
                    "make": "4geek"
                }
            ]
        },
        "deviceCapability": {
            "targets": [
                {
                    "targetValue": 1,
                    "exclude": false,
                    "targetLevel": 1,
                    "deviceCapabilityId": 1,
                    "deviceCapabilityName": "Phone calls"
                }
            ]
        },
        "deviceType": {
            "targets": [
                {
                    "targetValue": 4,
                    "exclude": false,
                    "targetLevel": 1,
                    "deviceTypeId": 4,
                    "deviceType": "Tablet"
                }
            ]
        },
        "geo": {
            "targets": [
                {
                    "targetValue": 232,
                    "exclude": false,
                    "targetLevel": 1,
                    "countryCode": "US",
                    "name": "United States"
                }
            ]
        },
        "hyperLocal": {
            "targets": [
                {
                    "targetValue": {
                        "latitude": 18.5203062,
                        "longitude": 73.8543185,
                        "radius": 2,
                        "radiusInKm": 2,
                        "radiusUnit": "km"
                    },
                    "exclude": false
                }
            ]
        },
        "hyperLocalDataSource": {},
        "inventory": {
            "targets": [
                {
                    "targetValue": 10043201,
                    "exclude": false,
                    "targetLevel": 2,
                    "name": "AA_PH-6439_Test_AU"
                },
                {
                    "targetValue": 10043197,
                    "exclude": false,
                    "targetLevel": 2,
                    "name": "RobotAuto_AU_with_all_formats-01-30-2019 15-36-27vcjqx"
                },
                {
                    "targetValue": 10043198,
                    "exclude": false,
                    "targetLevel": 2,
                    "name": "RobotAuto_AU_with_all_formats-01-30-2019 15-38-20jmsui"
                }
            ]
        },
        "ipRange": {
            "targets": [
                {
                    "targetValue": {
                        "from": "1.1.1.1",
                        "to": "12.12.12.12"
                    },
                    "exclude": false,
                    "targetLevel": 1
                }
            ]
        },
        "os": {
            "targets": [
                {
                    "targetValue": 153,
                    "exclude": false,
                    "targetLevel": 1,
                    "osTypeId": 5,
                    "osName": "webOS"
                }
            ]
        },
        "zip": {}
    }

In order to completely remove all targetings, following request needs to be sent:

Code Block
languagejs
linenumberstrue
collapsetrue
{
	"targeting": {}
}

Inventory Targeting

Use the Inventory Targeting to target individual Ad Unit/s or all Ad Units i.e., Run of Network.

Important Note:

  1. This API will validate targetValue i.e. the adUnit / adUnit Group targeted.
  2. User should make sure that same targetValues are not getting included / excluded at same time.

Request Parameters      

Parameter Name Type Required Validations Descriptions
targetLevelNumericYes

Should not be null.

Should not be empty

Target Level  represents the type of inventory being targeted.

The following are valid Target Levels for Inventory Targeting:

                       

Target LevelTargetDescription
-1Run of NetworkEntity is 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. 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, such adUnits are skipped in validation.


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 use Run of Inventory.

Run of Network can only be included and never be excluded.

Ad Unit GroupNumericImportant Note: Targeting on Ad Unit group is not supported as on date. This Target Level is 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 is to be included / excluded while targeting.

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

RON Targeting Example

Code Block
languagejs
linenumberstrue
{
	"inventory": {
		"targets": [
            {
              "targetLevel": -1
            }
    	]
	}
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Remove Inventory Targeting Example

Code Block
languagejs
linenumberstrue
{
	"inventory": {
		 "targets": []
	}
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

This will internally set RON as targeting.

Targeting on specific adUnits (Inclusion And Exclusion) Example

Code Block
languagejs
linenumberstrue
{
    "inventory": {
        "targets": [{
                "targetLevel": 2,
                "exclude": true,
                "targetValue": 298,
                "name": "AdUnit_ATF_US_News"
            },
            {
                "targetLevel": 2,
                "exclude": false,
                "targetValue": 13,
                "name": "AdUnit_Main_Page"
            }
        ]
    }
}

Error Codes For Inventory Targeting

Following errors may occur while configuring inventory targeting

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

Geography Targeting :

Use the Geography Targeting to target on specific set of Countries, Cities, Regions/States, and DMAs.

Important Note:

  1. This API will not validate targetValue  ( i.e. id's for respective targeting ).  You should retrieve the valid target details using Common Geo API and provide id's for respective targeting.
  2. Ensure that the same targetValues are not being included / excluded at the same time.

Request  Parameters

Parameter NameTypeRequiredValidationsDescriptions
targetLevelNumericYes

Should not be null.

Should not be empty

Geo information at various level such as Country, Region/State, City, DMA, etc. can be retrieved using targetValue.

The following are valid Target Levels for Geography Targeting:

Target LevelTargetDescriptionSample URL
1CountryCountry Level TargetingTo retrieve all the countries supported for Targeting: http://$URI_PREFIX/api/common/geo?filters=geoLevel eq 1&showAll=true 
2Region/StateRegion/State Level Targeting

To retrieve all the region/state for a specific country.

Example: For the United States - 

http://$URI_PREFIX/api/common/geo?dimensions=id,name,countryCode&filters=geoLevel EQ 2&filters=countryCode EQ US

3CityCity Level Targeting

To retrieve all the City for a particular RegionState

Example: For the state of New York - 

http://$URI_PREFIX/api/common/geo?dimensions=id,name,regionCode,countryCode&filters=geoLevel EQ  3&filters=countryCode EQ US&filters=regionCode EQ NY

You will need to use pagination parameters to retrieve more cities if available.

4DMADMA Level Targeting

We currently only support DMA for country United States Of America.

EXAMPLE: For country US

http://$URI_PREFIX/api/common/geo?filters=geoLevel EQ 4&filters=countryCode EQ US

You need to use pagination parameters to retrieve more DMA records if available.


targetValueNumeric

Yes

Should not be null.

Should not be empty.

TargetValue will contain reference value.

                            

Target TypeTarget Value Data TypeReference/Actual Value
CountryNumeric

Reference Value.   id  attribute from the response returned  by http ://$URI_PREFIX/api/common/geo  API

Region/StateNumericReference Value.   id  attribute from the response returned by  Common http ://$URI_PREFIX/api/common/geo  API
CityNumericReference Value.   id  attribute from the response returned by  Common http ://$URI_PREFIX/api/common/geo  API
DMANumericReference Value.   id  attribute from the response returned by  Common http ://$URI_PREFIX/api/common/geo  API


excludeBooleanYes

Default will be false.

Valid values can be true or false

The exclude parameter defines whether this targeting is to be included or excluded. By default, specified targetLevel and targetValue will be included as exclude parameter will be false.

You can either include or exclude the entities during targeting for entities at same level. E.g. You can include Country as United States but then, you cannot exclude other countries.as it will create a conflict during targeting.

However you can exclude states, cities from United state if you want. Thus, hierarchical exclusions are possible. A country can be included and some specific states within the country can be excluded.

Geo Targeting Example

Code Block
languagejava
linenumberstrue
{
 "geo": {
 "targets": [{
 "targetValue": 107,
 "exclude": true,
 "targetLevel": 1,
 "countryCode": "IN",
 "cityName": "India",
 "dmaCode": 0
 },
 {
 "targetValue": 162908,
 "exclude": false,
 "targetLevel": 2,
 "countryCode": "US",
 "cityName": "Virgin Islands",
 "dmaCode": 0
 },
 {
 "targetValue": 5818,
 "exclude": false,
 "targetLevel": 3,
 "countryCode": "IN",
 "cityName": "Pune",
 "dmaCode": 0
 },
 {
 "targetValue": 162688,
 "exclude": true,
 "targetLevel": 4,
 "countryCode": "US",
 "cityName": "New York",
 "dmaCode": 501
 }
 ]
 }
}

Remove all Geography Targeting Example

Code Block
languagejs
linenumberstrue
{
"geo": {
	"targets": []
 }
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Error Codes for Geography Targeting

Following errors may occur while configuring geography targeting

Sr. NoError CodesError MessageDescription
1.PH_MISSING_OR_INVALID_PARAMETERMissing or Invalid Target ValueWhen any target object contains NULL or empty target value
2.PH_MISSING_OR_INVALID PARAMETER_MSGMissing or Invalid Target LevelWhen any target object contains NULL or empty target level

Zip Targeting :

Use the Zip Targeting API to target on zip code belonging to specific country. While targeting zip codes, the country code is mandatory which you can retrieved using http://$URI_PREFIX/api/common/geo?filters=geoLevel  eq 1&showAll=true

Important Note:

  1. Zip targeting API validates the provided zip code against the country code. If zip code does not exist against the given country code, it will fail entire zip targeting call.  You should pass only valid set of zip codes where you want to set the targeting.
  2. User should make sure that same targetValues are not getting included / excluded at same time.

Request  Parameters        

Parameter NameTypeRequiredValidationsDescriptions
targetLevelNumericYes

Should not be null.

Should not be empty

You can retrieve the zip codes for given country/state and set them in targeting.

Following are valid Target Levels for Geography Targeting:         

Target LevelTargetDescriptionSample URL
5ZipZip/Postal Code

You can retrieve the supported zip codes by applying country/state level filter.

Example: Get the list of zip codes available in the system for Country  "United States" and State "New York"

https://$URI_PREFIX/api/common/zipcode?filters=countryCode EQ US&filters=regionCode EQ NY&pageNumber=1&pageSize=100

Since there are a large number of records at country/state level, you should use pagination and applicable filters to get a faster response.


targetValueNumeric

Yes

Should not be null.

Should not be empty.

Target Value can contain the actual  Zip Code and Country Code value. 

If you are doing Zip / Postal code level targeting (target level = 5) then target value should be actual zip code received in the https://$URI_PREFIX/api/common/zipcode API.

 
e.g. If you want to target for zip code for United States 

  1.  Actual Zip Code
  2. 2 letter ISO Country Code

Following are the supported data types

                  

Target TypeTarget Value Data TypeReference/Actual Value
Zip/Postal CodeString

Actual zip code

countryCodeString2 letter ISO country code


excludeBooleanYes

Default will be false.

Valid values can be true or false

This value indicates whether the zip code is to be included/excluded in targeting.

Zip Targeting Example

Code Block
languagejs
linenumberstrue
{
 "zip": {
 "targets": [{
 "targetValue": {
 "code": "13036",
 "countryCode": "US"
 },
 "exclude": false,
 "targetLevel": 5,
 "country": "United States",
 "regionName": "New York",
 "city": "Central Square",
 "code": "13036",
 "countryCode": "US"
 }, {
 "targetValue": {
 "code": "13411",
 "countryCode": "US"
 },
 "exclude": false,
 "targetLevel": 5,
 "country": "United States",
 "regionName": "New York",
 "city": "New Berlin",
 "code": "13411",
 "countryCode": "US"
 }, {
 "targetValue": {
 "code": "11040",
 "countryCode": "US"
 },
 "exclude": false,
 "targetLevel": 5,
 "country": "United States",
 "regionName": "New York",
 "city": "New Hyde Park",
 "code": "11040",
 "countryCode": "US"
 }, {
 "targetValue": {
 "code": "411036",
 "countryCode": "IN"
 },
 "exclude": false,
 "targetLevel": 5,
 "country": "India",
 "regionName": "Maharashtra",
 "city": "Pune",
 "code": "411036",
 "countryCode": "IN"
 }]
 }
}

Remove all Zip/Postal Code Targeting Example

Code Block
languagejs
linenumberstrue
{
	"zip": {
		"targets": []
	}
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Error Codes for Zip/Postal Code Targeting           

Following errors may occur while configuring Zip code targeting

Sr. NoError CodesError MessageDescription
1.PH_MISSING_OR_INVALID_PARAMETER
  1. Missing or Invalid Target Value
  2. Missing or Invalid Target Level
  3. Missing or Invalid countryCode
  4. Missing or Invalid Zip Code
  1. When any target object contains NULL or empty target value
  2. When specified wrong target Level
  3. When Invalid Country Code is provided
  4. When Invalid Zip Code is Provided for country
2.PH_DUPLICATE_ENTRIES_FOUNDDuplicate Zip Code IdWhen user includes the same zip during targeting.

Hyper Local Targeting :

Use the Hyper Local Data Source Targeting API to target the Line Item on Inventory containing the location coordinates derived by various techniques like GPS, IP address or user-provided, etc.

Request Parameters

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

Parameter NameTypeRequiredValidationsDescriptions
targetLevelNumericYes

Should not be null.

Should not be empty

Hyper Local has only a single target level, therefore it is requested to pass 1 during targeting. If you pass an invalid targetLevel API will silently ignore it.

You can retrieve the supported data source that may be used to get the location.

targetValueNumeric

Yes

Should not be null.

Should not be empty.

Retrieve the supported data source, which you may use to retrieve the location.


Code Block
languagejs
linenumberstrue
http://$URI_PREFIX/common/hyperlocaldatasource


 e.g. If you want to target line item only on GPS based location coordinates, then you should set 1.

Reference/Actual ValueData SourceDescription
1GPS/Location Services

If you want to target only on GPS derived Location coordinates.

2IP AddressIf you want to target on IP address derived from Location coordinates such as Max Mind, etc.
3User ProvidedIf you want to target on Location Coordinates if provided by the user, based on registration Data.


Hyper Local Targeting Example

Code Block
languagejs
linenumberstrue
{
 "hyperLocal": {
 "targets": [{
 "targetValue": {
 "latitude": 40.7127837,
 "longitude": -74.0059413,
 "radius": "0.5",
 "radiusUnit": "mi"
 },
 "exclude": false
 }]
 }
}

Remove all Hyper Local Targeting Example

Code Block
languagejs
linenumberstrue
{
"hyperLocal": {
	"targets": []
}
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Error Codes for Hyper Local Data Source Targeting

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

Sr. NoError CodesDescription
1.PH_MISSING_OR_INVALID_PARAMETERThis error occurs when any target object contains NULL or empty target value or an invalid value.
2.PH_DUPLICATE_ENTRIES_FOUNDThis error occurs when any target value is duplicated.

Browser Targeting :

Use Browser targeting API to target on a specific set of browsers.

Important Note:

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

Request  Parameters        

Parameter NameTypeRequiredValidationsDescriptions
targetLevelNumericYes

Should not be null.

Should not be empty.

This API enables targeting on browsers. It does not support granular level such as versions. Therefore, the targetLevel will always be  1.

Target LevelTargetDescriptionURL for obtaining target level list
1BrowserBrowser Targeting


Code Block
languagejs
linenumberstrue
http://$URI_PREFIX/api/common/browser



targetValueObject

Yes

Should not be null.

Should not be empty.

Target Value can contain the actual or reference value. It will depend on  target level you are targeting for.

e.g. If you want to target for browser Chrome then targetValue = 5

The following are supported data types:

Target TypeTarget Value Data TypeReference/Actual Value
BrowserNumericReference Value.   id  attribute from the response returned by  http://$URI_PREFIX/api/common/browser  API


excludeBooleanYes

Default will be false.

Valid values can be true or false.

This value indicates whether the browser to be included / excluded while targeting.

You can either include or exclude the browsers but not both at time.

Browser Targeting Example

Code Block
languagejs
linenumberstrue
{
    "browser": {
        "targets": [{
                "targetValue": 4,
                "exclude": false,
                "targetLevel": 1,
                "name": "Opera"
            },
            {
                "targetValue": 5,
                "exclude": false,
                "targetLevel": 1,
                "name": "Chrome"
            }
        ]
    }
}

Remove all Browser Targets Example

Code Block
languagejs
linenumberstrue
{
	"browser": {
		"targets": []
	}
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Error Codes for Browser Targeting

Following errors may occur while configuring browser targeting

Sr. NoError CodesError MessageDescription
1PH_MISSING_OR_INVALID_PARAMETERMissing or Invalid Target ValueWhen any target object contains NULL or an empty target value
2PH_DUPLICATE_ENTRIES_FOUNDDuplicate targets targetValue [id]When any targetValue is duplicated

Browser Language Targeting :

Browser Language Targeting API is used for targeting on browser languages.

Important Note:

  1. This API will not validate targetValue  ( i.e. id's for respective targeting ). Users should retrieve the valid target details using the  Common Browser Language API  and provide id's for respective targeting.
  2. Make sure that same targetValues are not getting included / excluded at same time.

Request Parameters        

Parameter NameTypeRequiredValidationsDescriptions
targetLevelNumericYes

Should not be null.

Should not be empty.

Browser language does not have a hierarchy and therefore, the targetLevel will be always 1.

               

Target LevelTargetDescriptionURL for obtaining target level list
1Browser LanguageBrowser Language for Targeting

You can retrieve the supported browser languages for targeting using following link. You can apply sorting on supported dimensions.


Code Block
languagejs
linenumberstrue
http://$URI_PREFIX/api/common/browserlanguage?dimensions=id,name&showAll=true&sort=name



targetValueNumeric

Yes

Should not be null.

Should not be empty.

Target Value can contain the actual or reference value. It will depend on which target level you are targeting for.

e.g. If you want to target for browser language English then targetValue = 23
 

The following are supported data types:

             

Target TypeTarget Value Data TypeReference/Actual Value
Browser LanguageNumericReference Value.   id  attribute from the response returned by Common API


excludeBooleanYes

Default will be false.

Valid values can be true or false.

This value indicates whether the browser language is to be included / excluded while targeting.

You can either include or exclude the browsers but not both at time.

Browser Language Targeting Example

Code Block
languagejs
linenumberstrue
{
 "browserLanguage": {
 "targets": [{
 "targetValue": 23,
 "exclude": true,
 "targetLevel": 1,
 "name": "English"
 }, {
 "targetValue": 32,
 "exclude": true,
 "targetLevel": 1,
 "name": "French"
 }, {
 "targetValue": 21,
 "exclude": true,
 "targetLevel": 1,
 "name": "German"
 }]
 }
}

Remove all Browser Language Targetings Example

Code Block
languagejs
linenumberstrue
{
"browserLanguage": {
 "targets": []
 }
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Error Codes for Browser Language Targeting

Following error codes may occur while configuring browser Language Targeting :

Sr. No Error Codes Error Message Description
1PH_MISSING_OR_INVALID_PARAMETERMissing or Invalid Target ValueWhen any target object contains NULL or an empty target value
2PH_DUPLICATE_ENTRIES_FOUNDDuplicate targets targetValue [id]When any targetValue is duplicated
 

Device Capability Targeting :

Use Device Capability Targeting to target on features supported by Mobile Devices.

Important Note:

  1. This API will not validate targetValue  ( i.e. id's for respective targeting ).  User should retrieve the valid target details using Common Device Capabilities API  and provide id's for respective targeting.
  2. Make sure that same targetValues are not getting included / excluded at same time.

Request Parameters        

Parameter NameTypeRequiredValidationsDescriptions
targetLevelNumericYes

Should not be null.

Should not be empty.

Device Capability has only one target level as there is no hierarchy.

               

Target LevelTargetDescriptionURL for obtaining target level list
1Device CapabilityDevice Capability Targeting

You can retrieve the supported device capabilities for targeting using the following URL. You can apply sorting on supported dimensions.

http://$URI_PREFIX/api/common/devicecapability?dimensions=id,name&sort=id


targetValueNumberic

Yes

Should not be null.

Should not be empty.

Target Value can contain the actual or reference value. It will depend on which target level you are targeting for.

e.g. If you want to target for device capability NFC support then targetValue = 6
 

The following are supported data types:

             

Target TypeTarget Value Data TypeReference/Actual Value
Device CapabilityNumericReference Value.   id  attribute from the response returned by  http://$URI_PREFIX/api/common /devicecapability


excludeBooleanYes

Default will be false.

Valid values can be true or false.

This value indicates whether the device capability is to be included / excluded while targeting.

Device Capability Targeting Example

Code Block
languagejs
linenumberstrue
{
    "deviceCapability": {
        "targets": [{
            "targetValue": 1,
            "exclude": false,
            "targetLevel": 1,
            "deviceCapabilityId": 1,
            "deviceCapabilityName": "Phone calls"
        }, {
            "targetValue": 5,
            "exclude": false,
            "targetLevel": 1,
            "deviceCapabilityId": 5,
            "deviceCapabilityName": "Touchscreen support"
        }, {
            "targetValue": 6,
            "exclude": false,
            "targetLevel": 1,
            "deviceCapabilityId": 6,
            "deviceCapabilityName": "NFC support"
        }]
    }
}

Remove all Device Targeting Example

Code Block
languagejs
linenumberstrue
{
"deviceCapability": {
 "targets": []
 }
}

Error Codes for Device Capability Targeting

Following error codes may occur while configuring Device Capability Targeting

Sr. NoError CodesError MessageDescription
1PH_MISSING_OR_INVALID_PARAMETERMissing or Invalid Target ValueWhen any target object contains NULL or an empty target value
2PH_DUPLICATE_ENTRIES_FOUNDDuplicate targets targetValue [id]When any targetValue is duplicated.

OS Targeting :

Use OS Targeting to target on Mobile Operating systems. This enables targeting on specific / All Major and its minor versions.

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 Common Mobile Operating System 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.

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

You can retrieve the operating system information using information at the version level ( Major / Minor ) using targetLevel.

The following are the valid Target Levels for OS targeting:

Target LevelTargetDescriptionURL for obtaining target level list
1OS NameTo set targeting at an OS level

You can retrieve all supported OS details using following URL

http://$URI_PREFIX/api/common/mobileOS?filters=osLevel eq 1&showAll=true

2OS Major VersionOS Major Version

If you want to target at specific operating system along with all its minor version, you can retrieve the OS details with Major version as follows.

E.g. Retrieving the Major versions of iOS. You have passosTypeId as filter received in osLevel eq 1 request. 

http://$URI_PREFIX/api/common/mobileOS?filters=osLevelEQ 2&filters=osTypeId EQ 1&pageNumber=1&sort=verMajor

3OS Minor VersionOS Minor Version

If you want to target at specific set of minor version for given operating system and its major version, you can retrieve the OS details with minor version as follows.

E.g. You want to target the line item on Android 3.2, Android 3.3. You have pass osTypeId as filter received in osLevel eq 2 request. 

http://$URI_PREFIX/api/common/mobileOS?filters=osLevelEQ 3&filters=osTypeId EQ 2&filters=verMajor EQ 3


targetValueNumberic

Yes

Should not be null.

Should not be empty.

Target Value can contain the actual or reference identifier. Iid received from /common/mobileOS/ API should be the input.

The following are supported data types:

Target TypeTarget Value Data TypeReference/Actual Value
OS NameNumericReference Value.  id attribute from the response returned by/common/mobileOS/ API
OS Major VersionNumericReference Value.  id attribute from the response returned by/common/mobileOS/ API
OS Minor VersionNumericReference Value.  id attribute from the response returned by/common/mobileOS/ API


excludeBooleanYes

Default will be false.

Valid values can be true or false.

This value indicates whether the OS is to be included / excluded while targeting.

OS Targeting Example

Code Block
languagejs
linenumberstrue
{
    "os": {
        "targets": [{
            "targetValue": 6,
            "exclude": false,
            "targetLevel": 1,
            "osTypeId": 1,
            "osName": "iOS"
        }, {
            "targetValue": 5,
            "exclude": true,
            "targetLevel": 2,
            "osTypeId": 1,
            "osName": "iOS 1",
            "verMajor": "1"
        }, {
            "targetValue": 4,
            "exclude": true,
            "targetLevel": 2,
            "osTypeId": 1,
            "osName": "iOS 2",
            "verMajor": "2"
        }, {
            "targetValue": 3,
            "exclude": true,
            "targetLevel": 2,
            "osTypeId": 1,
            "osName": "iOS 3",
            "verMajor": "3"
        }]
    }
}

Remove all OS Targeting Example

Code Block
languagejs
linenumberstrue
{
"os": {
	"targets": []
}
}

Error Codes for OS Targeting

Following error codes may occur while configuring OS Targeting

Sr. No Error Codes Error Message Description
1PH_MISSING_OR_INVALID_PARAMETERMissing or Invalid Target ValueWhen any target object contains NULL or an empty target value
2PH_DUPLICATE_ENTRIES_FOUNDDuplicate targets targetValue [id]When any targetValue is duplicated
 

Device Type Targeting :

Device Type Targeting is used to target on different types of devices like feature phone, smart phone etc.

Important Note:

  1. This API will not validate targetValue (that is, ID's for respective targeting).  Retrieve the valid target details using Common Mobile Device Type API and provide ID's for respective targeting.
  2. Make sure that the same targetValues are not getting included / excluded at same time.

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

Device Type has a single target level.

The following are the valid Target Levels for Device Type targeting:

               

Target LevelTargetDescriptionURL for obtaining target level list
1Device TypeDevice Type Targeting

You can retrieve all supported Devide Type details using following URL

http://$URI_PREFIX/api/common/mobileDeviceType


targetValueNumeric

Yes

Should not be null.

Should not be empty.

Target Value can contain a reference value.e.g., To target a Device Type Tablet then targetValue=2

The following are supported data types:

             

Target TypeTarget Value Data TypeReference/Actual Value
Device TypeNumericReference Value.   id  attribute from the response returned Common  API


excludeBooleanYes

Default will be false.

Valid values can be true or false.

This value indicates whether the Device Type is to be included / excluded while targeting the Line Item

Device Type Targeting Example

Code Block
languagejs
linenumberstrue
{
  "deviceType": {
      "targets": [
    {
      "targetValue": 1,
      "exclude": true,
      "targetLevel": 1,
      "deviceTypeId": 1,
      "deviceType": "Feature Phone"
    },
    {
      "targetValue": 2,
      "exclude": true,
      "targetLevel": 1,
      "deviceTypeId": 2,
      "deviceType": "Smart Phone"
    }
  ]
}}

Remove all Device Type Targeting Example

Code Block
languagejs
linenumberstrue
{
"deviceType": {
	"targets": []
}
}

Error Codes for Device Type Targeting

Following error codes may occur while configuring Device Type Targeting

Sr. No Error Codes Error Message Description
1PH_MISSING_OR_INVALID_PARAMETERMissing or Invalid Target ValueWhen any target object contains NULL or an empty target value
2PH_DUPLICATE_ENTRIES_FOUNDDuplicate targets targetValue [id]When any targetValue is duplicated
 

Device Manufacturer Targeting :

Use Device Manufacturer Targeting  to target on specific make/manufacturer and it's available models.

Important Note:

  1. This API will not validate targetValue  ( i.e. id's for respective targeting ).  Retrieve the valid target details using Common Mobile Device API and provide id's for respective targeting.
  2. Make sure that the same targetValues are not getting included / excluded at same time.

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

The Target Level represents the granularity of the selected manufacturer/model.

The following are the valid Target Levels for Device Manufacturer targeting:

                     

Target LevelTargetDescriptionURL for obtaining target level list
1Manufacturer/ModelManufacturer Level Targeting
  • To retrieve the All device list by Make / Manufacturer

    http://$URI_PREFIX/api/common/mobileDevice?filters=deviceLevel eq 1&showAll=true
     
  • You can search for specific Make / Manufacturer, e.g., Find all devices for Apple 

    http://$URI_PREFIX/api/common/mobileDevice?dimensions=id,deviceValue,make,deviceTypeId,deviceLevel&filters=makeLIKE *Apple*,deviceValue LIKE *Apple*&pageNumber=1&sort=deviceValue,make
     
    • List the device model belong to particular make, e.g., List device model for Apple. Here id EQ 2 is id for Apple Make. 

      https://$URI_PREFIX/api/common/mobileDevice?filters=deviceLevel EQ 2&filters=id EQ 2&pageNumber=1&sort=deviceValue&useAllDimensions=true
2ModelDevice Model 


targetValueNumeric

Yes

Should not be null.

Should not be empty.

Target Value can contain the actual or reference value. It will depend on which target level you are targeting.

The following are supported data types:

                  

Target TypeTarget Value Data TypeReference/Actual Value
ManufacturerNumericReference Value.   id  attribute from the response returned by  http://$URI_PREFIX/api/common/mobileDevice  API.
ModelNumericReference Value.   id  attribute from the response returned by  http://$URI_PREFIX/api/common/mobileDevice  API


excludeBooleanYes

Default will be false.

Valid values can be true or false.

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


Device Manufacturer Targeting Example

Code Block
languagejs
linenumberstrue
 {
"device": {
            "targets": [
                {
                    "targetValue": 10692,
                    "exclude": false,
                    "targetLevel": 1,
                    "deviceTypeId": 3,
                    "deviceValue": "4geek",
                    "make": "4geek"
                }
            ]
        }
}

Remove all Device Manufacturing Example

Code Block
languagejs
linenumberstrue
{
"device": {
	"targets": []
}
}

Error Codes for Device Manufacturing Targeting

Following error codes may occur while configuring Device Manufacturing Targeting

Sr. No Error Codes Error Message Description
1PH_MISSING_OR_INVALID_PARAMETERMissing or Invalid Target ValueWhen any target object contains NULL or an empty target value
2PH_DUPLICATE_ENTRIES_FOUNDDuplicate targets targetValue [id]When any targetValue is duplicated
 

Connection Type Targeting :

Use the Connection Type Targeting API to target on Mobile devices with a specific connection type.  

Important Note:

  1. This API will not validate targetValue  ( i.e. id's for respective targeting ).  Retrieve the valid target details using Common Connection Type API and provide id's for respective targeting.
  2. Make sure that the same targetValues are not getting included / excluded at same time.

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

This API allows you to target Connection Types. It does not have any hierarchical relation. Hence, the targetLevel will be always 1.

               

Target LevelTargetDescriptionURL for obtaining target level list
1Connection TypeConnection Type Targeting

http://$URI_PREFIX/api/common/pmconnectiontype


targetValueNumeric

Yes

Should not be null.

Should not be empty.

Target Value can contain the actual or reference value. It will depend on which target level you are targeting.

e.g., if you want to target for connection type WiFi then targetValue=2

The following are supported data types:

             

Target TypeTarget Value Data TypeReference/Actual Value
Connection TypeNumericReference Value.   id  attribute from the response returned by http://$URI_PREFIX/api/common/pmconnectiontype


excludeBooleanYes

Default will be false.

Valid values can be true or false.

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

Connection Type Targeting Example

Code Block
languagejs
linenumberstrue
{
	"connectionType": {
            "targets": [
                {
                    "targetValue": 1,
                    "exclude": false,
                    "targetLevel": 1,
                    "name": "Cellular"
                }
            ]
        }
}

Remove all Connection Type Targeting Example

Code Block
languagejs
linenumberstrue
{
	"connectionType": {
            "targets": []
	}
}

Error Codes for Connection Type Targeting

Following error codes may occur while configuring Connection Type Targeting

Sr. No Error Codes Error Message Description
1PH_MISSING_OR_INVALID_PARAMETERMissing or Invalid Target ValueWhen any target object contains NULL or an empty target value
2PH_DUPLICATE_ENTRIES_FOUNDDuplicate targets targetValue [id]When any targetValue is duplicated
 

IP Range Targeting :

Use the IP Range Targeting to target on IP Addresses.

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.

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

Code Block
languagejs
linenumberstrue
{
    "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:

Code Block
languagejs
linenumberstrue
{
    "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.

IP Range Targeting Example

Code Block
languagejs
linenumberstrue
{
	"ipRange": {
                  "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
                }
            ]
        }
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Remove all IP Targeting Example

Code Block
languagejs
linenumberstrue
{
	"ipRange": {
                  "targets": []
	}
}

Error Codes for IP Range Targeting

Following errors may occur while IP Range Targeting        

Sr. NoError CodesError MessageDescription
1.PH_MISSING_OR_INVALID_PARAMETERMissing or Invalid Target ValueWhen any target object contains NULL or is an empty target value
2.PH_FROM_ENTITY_GREATER_THAN_TO_ENTITYFrom IP must be less than or equal to IPWhen From/To contains an Invalid IP Address
3.PH_DUPLICATE_ENTRIES_FOUNDDuplicate IP Range (e.g., 172.16.4.50 - 172.16.4.50)When a duplicate IP Address range is input.

Custom Key Targeting :

Use the Custom Key Value targeting API to target on key value pairs as per  common user characteristic, e.g. ( Gender, Age, Income, keywords ).

Unified Ad Server allows you to create Text and Numeric type of custom keys and allows you to set the pre-defined / free-form text values as per your needs. Before you proceed to set the key value targeting,  you will be required to define the key and its values using Custom Key API for your account. The custom keys that are "Inactive" / "Archived" will not be visible during targeting.

You can use operator API,  https://api.pubmatic.com/v1/uas/operators/, to retrieve the supported operators for key value pair while targeting. You can find more details in the Operator API .

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

The Target Level will contain reference value. It will always be 1.

targetValueObject

Yes

Should not be null.

Should not be empty.

Target Value object contains the following set of attributes required to set the key value targeting.

Code Block
languagejs
linenumberstrue
{
    "customKey": {
        "id": 1
    },
    "customValue": {
        "value": "23"
    },
    "operator": {
        "id": 1
    },
    "setId": 1
}

    

Parameter NameMandatoryDescription
customKeyYes

Key Identifier for the key

Customkey to be associated should be in active/inative status

customValueYesValue should be given as a String. Will be interpreted and validated as per key type (Numeric or Text).
operatorYesOperator identifier that you want to apply on key value. System will interpret and validate it as per key type (Numeric or Text).
setId/groupIdYes

Set represents the logical grouping of your condition.

Use Case 1: Set containing same keys are treated as "OR" condition. E.g., S1: (color=blue OR color=red).

                        

customKeycustomValuegroupIdsetIdOperator
1"blue"111
1"red"111

Use Case 2: Set containing different keys are treated as "AND" condition. E.g., S2: (color=red ADN shape=rectangle)

                        

customKeycustomValuegroupIdsetIdOperator
1"blue"111
21"rectangle"211

More Examples:

S1: (color=blue OR color=red) AND shape=rectangle 

                               

customKeycustomValuegroupIdsetIdOperator
1"blue"111
1"red"111
2"rectangle"211

S1: (color=blue AND shape=circle) OR S2: (color=red AND shapes=rectangle)

                                      

customKeycustomValuegroupIdsetIdOperator
1"blue"111
21"circle"211
1"red"121
2"rectangle"221

 groupId: -created dynamically by API. Targets with same custom key have same groupId.

                     


excludeBooleanYes

Default will be false.

API does not allow you to set the exclude as true since targeting on key value only allowed to include.

If you pass exclude with true, API does not honor it and silently ignore it.

Custom Key Targeting Example

Code Block
languagejs
linenumberstrue
{
	"customKey": {
                "targets": [{
                "targetValue": {
                    "customKey": {
                        "id": 16,
                        "name": "Age In Years",
                        "status": {
                            "id": 1
                        }
                    },
                    "operator": {
                        "id": 7,
                        "name": "IS BETWEEN"
                    },
                    "customValue": {
                        "value": "20-35"
                    },
                    "groupId": 1,
                    "setId": 1
                },
                "exclude": false,
                "targetLevel": 1
            }, {
                "targetValue": {
                    "customKey": {
                        "id": 1,
                        "name": "Gender",
                        "status": {
                            "id": 1
                        }
                    },
                    "operator": {
                        "id": 1,
                        "name": "IS"
                    },
                    "customValue": {
                        "value": "Male"
                    },
                    "groupId": 2,
                    "setId": 1
                },
                "exclude": false,
                "targetLevel": 1
            }]
        }
}

Remove all Custom Keys Example

Code Block
languagejs
linenumberstrue
{
	"customKey": {
                "targets": []
	}
}

Error Codes for Custom Key Value Targeting

Following error codes may occur while configuring custom key targeting

Sr. No Error Codes Error Message Description
1.PH_MISSING_OR_INVALID_PARAMETERMissing or Invalid Custom Key.

When any target object contains an invalid or no Custom Key.

When the setId field is invalid due to one of the following circumstances:

  • It is null.
  • It does not start with 1.
  • When multiple entries are present, it is not in consecutive order.
2.PH_DUPLICATE_ENTRIES_FOUNDDuplicate targets targetValue - customKey.idtarget.id.When targeting already exists with the same set of provided values: -key, value, operator and in the same set.
3.PH_UNSUPPORTED_CUSTOM_VALUECustom Value 23yy not supported.Validation error based on key type.
4.PH_UNSUPPORTED_OPERATOROperator CONTAINS not supportedValidation error based on key type.
5.PH_ATTEMPT_TO_ASSOCIATE_WITH_UNSUPPORTED
_STATUS_ENTITY_MSG
Custom key to be associated is in archive status.Validation of customkey status.

Audience Targeting :

Use the Audience targeting API to target various audience segments.

Important Note:

  • Ensure that different targetValues of the same targetLevel are not being included and excluded at same time.
  • Unlike other targeting API's, which use Common API for targeting details, Audience Targeting uses Audience API to fetch the audience segment details. For more details please refer Audience API

Request Body

The API accepts array of target objects, where each object must contain the following attributes.

Parameter Name/DimensionsTypeRequiredValidationsDescription
targetLevelNumericYes
  1. Target Level should not be null
  2. By default targetLevel is 1
  3. No other targetLevel is supported for Audience Targeting other than 1.

The following are the valid Target Levels for Audience targeting:

             

Target LevelTargetDescription
1Audience SegmentYou can retrieve the audiences by using the Audience API URL: 

http://{domainName}/audience/audiences?accountId={accountId}&accountType=PUBLISHER&audienceType=ALL_AUDIENCE

By default you get the audiences of audience type MY_AUDIENCE.


targetValueNumericYes
  1. Target Value should not be null.
  2. Target Value should be a valid Audience Id
  3. Target Value should be a Audience Id. Audience can be of MY_AUDIENCE type as well as SHARED_AUDIENCE.

Target Value will contain audience Id value.

             

Target TypeTarget Value Data TypeReference/Actual Value
Audience TargetNumericReference Value Id attribute from the response returned by Audience API.

          


Request Audience Target

Code Block
languagejs
linenumberstrue
{

    "targets": [

        {

            "targetValue": 1234,

            "exclude": false,

            "targetLevel": 1

        }

    ]

}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍


excludeBooleanYes
  1. Valid values can be true or false
  2. By default the exclude value is false if not passed.
This value indicates whether the Audience to be included/excluded while targeting the Line Item.

Audience Targeting Example

Code Block
languagejs
linenumberstrue
{
	"audience": {
	 "targets": [
        {
            "targetValue": 24711,
            "exclude": false,
            "targetLevel": 1,
            "name": "Test Audience 1 - 130917",
            "dataProviderId": 12,
            "dataProviderName": "Lotame",
            "enabled": 1
        },
        {
            "targetValue": 24712,
            "exclude": false,
            "targetLevel": 1,
            "name": "Test Audience 2 - 130917",
            "dataProviderId": 12,
            "dataProviderName": "Lotame",
            "enabled": 1
        }
    ]
	}
 }‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Remove all Audience Targeting Example

Code Block
languagejs
linenumberstrue
{
	"audience": {
		"targets": []
	}
}

Error Codes for Audience Targeting

Following errors may occur while targeting audience:

Sr. NoError CodesDescription
1.PH_MISSING_OR_INVALID_PARAMETER

This error occurs if a user does not provide any mandatory value or provides an invalid value.

This error can occur for following fields:

  • targetValue (If provided as null. If some value is provided and you get this error then it means that the audience id is invalid.)
  • targetLevel (Id provided as null or some value other than 1)
2.PH_DUPLICATE_ENTRIES_FOUNDThis error occurs if a user attempts to provide duplicate audience targets in a request, e.g., same targetValue.
3.PH_LI_DISABLED_AUDIENCE_FOR_TARGETThis error occurs if a user tries to target a disabled audience for the line item.

Hyper Local Data Source Targeting :

Use Hyper Local Data Source Targeting API to target on Central Location coordinates and the given radius in miles and kilometers.

Important Note:

  1. It validates the latitude ( -90 to 90 ) and longitude -180 to 180 range only.
  2. It only supports area inclusion and not exclusion.

Request Parameters

Parameter NameTypeRequiredValidationsDescriptions
targetValueObject

Yes

Should not be null.

Should not be empty.

Target Value will contain the following attributes:   

  1. Valid range of latitude.
  2. Valid range of longitude.
  3. Radius units must be "km" or "mi"
excludeBooleanYes

Default will be false.

It does not allow you to set the exclude as true since targeting on location only allows include.

If you pass exclude with true, the API does not honor it and silently ignores it.

Hyper Local Data Source Targeting Example

Code Block
languagejs
linenumberstrue
{
	"targets": [{
        "targetValue": {
            "latitude": 40.71278370,
            "longitude": -74.00594130,
            "radius": 0.5000,
            "radiusUnit": "mi"
        },
        "exclude": false
    }]
}

Remove all Hyper Local Data Source Targeting Example

Code Block
languagejs
linenumberstrue
{
	"targets": []
}

Error Codes for Hyper Local Data Source Targeting

Following errors occur while configuring Hyper local Data Source Targeting

Sr. NoError CodesError MessageDescription
1.PH_MISSING_OR_INVALID_PARAMETER
  1. Missing or Invalid Target Value
  2. Missing or Invalid radius unit.
  3. Missing or Invalid latitude.
  4. Missing or Invalid longitude.
  5. Missing or Invalid radius.
  1. When any target object contains NULL or empty target value
  2. When radiusUnit is not either mi / km.
  3. When latitude is not in valid range.
  4. When longitude is not in valid range.
  5. When user is passing 0 as radius