Page tree


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


Description

Use Device Manufacturer Targeting API to deliver the line items on a specific make/manufacturer and itts available models.

Important Note:

  1. This API will not validate targetValue  ( i.e. id's for respective targeting ) provided in the POST call.  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 for same line item.

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/devicesPOSTAdd/Update/Remove Manufacturer Targeting for the Line Item LevelConfigure Manufacturer Targeting
/lineitems/{lineItemId}/targets/devicesGETRetrieve Manufacturer Targeting Details for a Line ItemRetrieve Targeted Manufacturers for a Line Item


Configure Manufacturer Targeting

Overview

This API enables you to add, update or remove Device Manufacturer 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.

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.

You can either include or exclude the entities during targeting for given line time for entities at same level. E.g. You can either include or exclude Make / Manufacturer  OR Include particular Make / Manufacturer and exclude Models belong to it. 

Sample Request URL

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

Sample Request JSON


Note: always pass targetLevel =1

Target on "Apple" Make / Manufacturer and exclude models like "Apple iPAD 1",



"Apple iPAD 2", "Apple iPhone (3G)"

    

{
    "targets": [{
        "targetLevel": 1,
        "exclude": false,
        "targetValue": 2
    }, {
        "targetLevel": 1,
        "exclude": true,
        "targetValue": 105
    }, {
        "targetLevel": 1,
        "exclude": true,
        "targetValue": 106
    }, {
        "targetLevel": 1,
        "exclude": true,
        "targetValue": 98
    }]
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

  

Sample Request JSON: To Remove all Manufacturer Targeting for a LIne Item

{
    "targets": [ ]
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍


Response 

Sample Response JSON

    

{
  "entity": {
    {
        targetid associated with lineitem},
        "isPreset": 0
 },
  "targets": [
    {
      "targetValue": 1,
      "exclude": true,
      "targetLevel": 1,
      "deviceTypeId": 1,
      "deviceType": "Feature Phone"
    },
    {
      "targetValue": 2,
      "exclude": true,
      "targetLevel": 1,
      "deviceTypeId": 2,
      "deviceType": "Smart Phone"
    }
  ]
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Retrieve Targeted Manufacturers for a Line Item

Overview

This API enables you to retrieve Device Manufacturers 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.

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

You can either include or exclude the entities during targeting for given line time for entities at same level. E.g. You can either include or exclude Make / Manufacturer  OR Include particular Make / Manufacturer and exclude Models belong to it. 

Sample Request URL

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


Response

Sample Response JSON

{
    "targets": [{
        "targetValue": 2,
        "exclude": false,
        "targetLevel": 1,
        "deviceTypeId": 3,
        "deviceValue": "Apple",
        "make": "Apple"
    }, {
        "targetValue": 105,
        "exclude": true,
        "targetLevel": 2,
        "deviceTypeId": 4,
        "deviceValue": "Apple iPAD 1",
        "make": "Apple",
        "model": "iPAD 1"
    }, {
        "targetValue": 106,
        "exclude": true,
        "targetLevel": 2,
        "deviceTypeId": 4,
        "deviceValue": "Apple iPAD 2",
        "make": "Apple",
        "model": "iPAD 2"
    }, {
        "targetValue": 98,
        "exclude": true,
        "targetLevel": 2,
        "deviceTypeId": 2,
        "deviceValue": "Apple iPhone (3G)",
        "make": "Apple",
        "model": "iPhone (3 G)"
    }]
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍


Error Codes For Device Manufacturer Targeting

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

                                 

Sr. No Error Codes Error Message Description
1.PH_ACCESS_DENIEDAccess DeniedWhen provide lineitemid is not exists or you don't have an access to line item to perform edit operation.
2.PH_MISSING_OR_INVALID_PARAMETERMissing or Invalid Target ValueWhen any target object contains NULL or empty target value
3.PH_MISSING_OR_INVALID_PARAMETERMissing or Invalid Target LevelWhen Invalid Line Item Id is provided in the request
4.PH_DUPLICATE_ENTRIES_FOUNDDuplicate targets targetValue [id]When any targetValue duplicated during POST request



Version 0.1