Custom Key Value 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

You can use the Custom Key Value targeting API to target the Line Item on key value pairs as per your common user characteristic, e.g. ( Gender, Age, Income, keywords ). The custom key that are "Inactive" / "Archived" will not be visible during targeting.

 

Unified Ad Server allows you to create Text and Numeric type of custom keys and allow you to set the pre-define / free-form text values as per your needs. Before you proceed to set the key value targeting on a Line Item,  you will be required to define the key and its values using Custom Key API for your account.

 

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

 

If a line item is targeted on custom key-value, the ad server only serves a line item when you will pass the key values either through Ad Unit Script / Ad Server API.

Supported Operations 

                     

Method PathHTTP MethodDescriptionLink to Definition
/lineitems/{lineItemId}/targets/customkeysPOSTAdd/Update/Remove Custom Key Value Targeting for the Line ItemConfigure Custom Key Value Targeting
/lineitems/{lineItemId}/targets/customkeysGETRetrieve Custom Key Value Targeting Details for a Line ItemRetrieve Targeted Custom Key Values for a Line Item

 

Configure Custom Key Value Targeting

Overview

This API enables you to add, update or remove Custom Key Value Targets 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 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 targetig.

    
{
    "customKey": {
        "id": 1
    },
    "customValue": {
        "value": "23"
    },
    "operator": {
        "id": 1
    },
    "setId": 1
}
                            
Parameter NameMandatoryDescription
customKeyYes

Key Identifier for which you want to set

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 be interpreted and validated 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.

Sample Request URL

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

Sample Request JSON

Sample request for targeting Line Item on ( "Age in Years" IS BETWEEN 20-35 and "GENDER: IS Male)

{
    "targets": [{
        "targetValue": {
            "customKey": {
                "id": 16
            },
            "operator": {
                "id": 7
            },
            "customValue": {
                "value": "20-35"
            },
            "groupId": 1,
            "setId": 1
        }
    }, {
        "targetValue": {
            "customKey": {
                "id": 1
            },
            "operator": {
                "id": 1
            },
            "customValue": {
                "value": "Male"
            },
            "groupId": 1,
            "setId": 1
        }
    }]
}

Response 

Sample Response JSON

{
    "entity": {
        "id": {targetid associated with lineitem},
        "isPreset": 0
    },
    "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
    }]
}

Validations For Custom Key Value Targeting

Sr. NoEntityDescriptionRemarks
1Custom KeyMissing custom keycustomKey{ } object missing in json
2Custom KeyInvalid custom key
  1. customKey.Id is not a valid id for that account.
  2. customKey is not in Active state.
3Operator

Missing Operator

operator{} object missing in json
4OperatorInvalid Operatoroperator is not defined in the system
5Operator

Invalid type of Operator.

Should not apply a numeric type operator to text type value and vice-versa.

In db we have the following operators.

Following operators will be available for text keys: IS, IS NOT, CONTAINS, DOES NOT CONTAIN, STARTS WITH, ENDS WITH

Following operators will be available for numeric keys: IS, IS NOT, IS GREATER THAN, IS LESSER THAN, IS NOT GREATER THAN, IS NOT LESSER THAN, IS BETWEEN

Following operators will be available for both types of  keys: IS, IS NOT,

6Custom ValueIn case of numeric values (or keys) only numbers and ranges are allowed. 
7Set IdMissing set IdWe assume that setId provided by the UI will be correct, so we don't validate its value. No Invalid test case.
8Group IdSame groupId for same key in same set or across sets for a given lineitem targeting 
9Group IdDifferent groupId for different key in the same set or across sets for a given lineitem targeting 

 

Retrieve Targeted Custom Key Values for a Line Item

 

Overview

This API enables you to retrieve Custom Key Value Targets 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 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 targetig.

    
{
    "customKey": {
        "id": 1
    },
    "customValue": {
        "value": "23"
    },
    "operator": {
        "id": 1
    },
    "setId": 1
}
                            
Parameter NameMandatoryDescription
customKeyYesKey Identifier for which you want to set
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 be interpreted and validated 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.

Sample Request URL

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

Response

Sample Response JSON

 "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
    }]
}

Validations For Custom Key Value Targeting

                                                               

Sr. NoEntityDescriptionRemarks
1Custom KeyMissing custom keycustomKey{ } object missing in json
2Custom KeyInvalid custom key
  1. customKey.Id is not a valid id for that account.
  2. customKey is not in Active state.
3Operator

Missing Operator

operator{} object missing in json
4OperatorInvalid Operatoroperator is not defined in the system
5Operator

Invalid type of Operator.

Should not apply a numeric type operator to text type value and vice-versa.

In db we have the following operators.

Following operators will be available for text keys: IS, IS NOT, CONTAINS, DOES NOT CONTAIN, STARTS WITH, ENDS WITH

Following operators will be available for numeric keys: IS, IS NOT, IS GREATER THAN, IS LESSER THAN, IS NOT GREATER THAN, IS NOT LESSER THAN, IS BETWEEN

Following operators will be available for both types of  keys: IS, IS NOT,

6Custom ValueIn case of numeric values (or keys) only numbers and ranges are allowed. 
7Set IdMissing set IdWe assume that setId provided by the UI will be correct, so we don't validate its value. No Invalid test case.
8Group IdSame groupId for same key in same set or across sets for a given lineitem targeting 
9Group IdDifferent groupId for different key in the same set or across sets for a given lineitem targeting 

Error Codes for Custom Key Value Targeting

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

 

Sr. NoError CodesError MessageDescription
1.PH_MISSING_OR_INVALID_PARAMETERMissing or Invalid Custom Key.When any target object contains an invalid or no Custom Key.
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_MSGCustomkey to be associated is in archive statusValidation of customkey status.

 

 

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 17

Attachments

    Outcomes