Audience Targeting API (UAS)

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

Description
Supported Operations 
Request Body
Examples For Supported Operations 

Error Codes For Audience Targeting

 

For more information about UAS Line Item Targeting Services, refer to Line Item Targeting Services (UAS)

 

Description

Use the Audience targeting API to target various audience segments on a Line Item.

Important Note:

  • Ensure that different targetValues of the same targetLevel are not being included and excluded at same time for same line item.

 

This API must be called after creating/updating a Line Item successfully since it requires a Line Item Id during targeting.

 

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.  

 

Supported Operations

                     

Method PathHTTP MethodDescriptionLink to Definition
/lineitems/{lineItemId}/targets/audiencesPOSTAdd/Edit/Remove Audience targeting for the Line ItemConfigure Audience Targets

/lineitems/{lineItemId}/targets/audiences

GETRetrieve the Audience targeting details for a Line Item.Retrieve Targeted Audiences for a Line Item

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
{

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

Examples for Supported Operations

Add/Edit/Remove Audience Targets 

To Add Audience Targets on a Line Item

                 

URLhttps://api.pubmatic.com/v1/uas/lineitems/{lineItemId}/targets/audiences/
HTTP MethodPOST
Sample Request

To target a line item on specific Audience segments:

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

 

Request Body  

{
    "targets": [{
        "targetLevel": 1,
        "exclude": false,
        "targetValue": 24711
    }, {
        "targetLevel": 1,
        "exclude": false,
        "targetValue": 24712
    }]
}
Sample Response

Response Body

    
{
    "entity": {
        "account": {
            "id": { Account ID associated with the Target}
        },
        "id": { target ID associated with Line Item},
        "isPreset": 0,
        "url": "http://api.pubmatic.com/v1/uas/"
    },
    "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
        }
    ]
}

 

 

To Remove All Audience Targets for a Specific Line Item

                 

URLhttps://api.pubmatic.com/v1/uas/lineitems/{lineItemId}/targets/audiences/ 
HTTP MethodPOST
Sample Request

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

 

Request Body

   
{
    "targets": []
}
Sample Response

Response Body

    

{
    "entity": {
        "account": {
            "id": { Account ID associated with the Target}
        },
        "id": { target ID associated with Line Item},
        "isPreset": 0,
        "url": "http://api.pubmatic.com/v1/uas/"
    },
    "targets": []
}

 

Retrieving Targeted Audiences for a Line Item

                 

URLhttps://api.pubmatic.com/v1/uas/lineitems/{lineItemId}/targets/audiences/ 
HTTP MethodGET
Sample Requesthttps://api.pubmatic.com/v1/uas/lineitems/{lineItemId}/targets/audiences/ 
Sample Response

Response Body

   
{
    "targets": [
        {
            "targetValue": 24711,
            "exclude": false,
            "name": "Test Audience 1 - 130917",
            "dataProviderId": 12,
            "dataProviderName": "Lotame",
            "enabled": 1
        },
        {
            "targetValue": 24712,
            "exclude": false,
            "name": "Test Audience 2 - 130917",
            "dataProviderId": 12,
            "dataProviderName": "Lotame",
            "enabled": 1
        }
    ]
}

 

Error Codes for Audience Targeting

                            

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.
4.PH_ACCESS_DENIEDThis error occurs if a user provides a line item Id that does not exist or the user does not have access to that line item to perform edit operations.

 

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

Attachments

    Outcomes