Carrier Targeting API (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 Carrier Targeting API to deliver the line items for a specific set of carriers.

Important Note:

  • This API will not validate targetValue (i.e., Id's for respective targeting) that is provided in the POST call. Refer to valid target details using Common Mobile Carrier API and provide Id's for respective targeting.
  • Ensure that the same targetValues are not included/excluded at the same time for the same line item.

 

This API must be called after creating/updating a Line Item successfully.

Known Issues:

  • Duplicate Target objects check
  • Same target level cannot be included/excluded at the same time.

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/carriersPOSTAdd/Remove/Update carrier targeting for the Line ItemConfigure Carrier Targeting
/lineitems/{lineItemId}/targets/carriersGETRetrieve the carrier targeting details for {lineItemid}

Retrieving Targeted Carriers for Line Item

 

 

Configure Carrier Targeting

Overview

Use this API protocol to add, update or delete a Carrier from 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.

This API enables targeting on a carrier and not at a more granular level. Therefore, targetLevel will always be 1.

The following are the valid Target Levels for carrier targeting.

               
Target LevelTargetDescriptionURL for obtaining target level list
1CarrierCarrier Targetinghttp://$URI_PREFIX/common/mobileCarrier
targetValueString NumericYes

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
CarrierNumericReference Value. id attribute from the response returned by the Common API.

When passing the reference value, you must pass the value of the id attribute return in the Common API response as follows:

    
"items":
   [
       {
           "id": 1,
           "carrierValue": "UnDefined",
           "groupName": "UnDefined",
       },
       {
           "id": 2,
           "carrierValue": "2degrees Mobile",
           "groupName": "2degrees Mobile",
       },
       {
           "id": 3,
           "carrierValue": "Aether",
           "groupName": "Aether",
       },
 
       ...
       ...
   ]
excludeBooleanYes

Default will be false.

Valid values can be true or false.

This value indicates whether the carrier should be included/excluded while targeting the Line Item.

Sample Request URL

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

Sample Request JSON

Note: Always pass targetLevel=1

    

{
    "targets": [
        {
            "targetValue": 3,
            "targetLevel": 1,
            "exclude": true
        },
        {
            "targetValue": 2,
            "targetLevel": 1,
            "exclude": true
        }
    ]
}

 

To remove all carriers targeting for line item:

{
    "targets": []
}

Sample Response JSON


{
  "entity": {
    "id": 1
  },
  "targets": [
    {
      "targetValue": 3,
      "exclude": true,
      "targetLevel": 1,
      "carrierValue": "Aether",
      "groupName": "Aether"
    },
    {
      "targetValue": 2,
      "exclude": true,
      "targetLevel": 1,
      "carrierValue": "2degrees Mobile",
      "groupName": "2degrees Mobile"
    }
  ]
}

 

Retrieving Targeted Carriers for Line Item

 

Overview

This API enables you to retrieve the Carrier Targeting Details 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.

 

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 enables targeting on a carrier and not at a more granular level. Therefore, targetLevel will always be 1.

The following are the valid Target Levels for carrier targeting.

               
Target LevelTargetDescriptionURL for obtaining target level list
1CarrierCarrier Targetinghttp://$URI_PREFIX/common/mobileCarrier
targetValueString NumericYes

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
CarrierNumericReference Value. id attribute from the response returned by the Common API.

When passing the reference value, you must pass the value of the id attribute return in the Common API response as follows:

   
"items":
   [
       {
           "id": 1,
           "carrierValue": "UnDefined",
           "groupName": "UnDefined",
       },
       {
           "id": 2,
           "carrierValue": "2degrees Mobile",
           "groupName": "2degrees Mobile",
       },
       {
           "id": 3,
           "carrierValue": "Aether",
           "groupName": "Aether",
       },

       ...
       ...
   ]
excludeBooleanYes

Default will be false.

Valid values can be true or false.

This value indicates whether the carrier should be included/excluded while targeting the Line Item.

Sample Request URL

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

 

Sample Response JSON

    



{
  "targets": [
    {
      "targetValue": 3,
      "exclude": true,
      "targetLevel": 1,
      "carrierValue": "Aether",
      "groupName": "Aether"
    },
    {
      "targetValue": 2,
      "exclude": true,
      "targetLevel": 1,
      "carrierValue": "2degrees Mobile",
      "groupName": "2degrees Mobile"
    }
  ]
}

Error Codes for Carrier Targeting

                            

Sr. NoError CodesDescription
1.PH_ACCESS_DENIEDWhen lineitemid provided does not exist or you do not have access to the line item to perform edit operation.
2.PH_MISSING_OR_INVALID_PARAMETERWhen any target object contains NULL or empty target value.
3.PH_MISSING_OR_INVALID_PARAMETERWhen invalid Line Item Id is provided in the request.
4.PH_DUPLICATE_ENTRIES_FOUNDWhen any targetValue duplicated during POST request.

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