Custom Key Value Associations API (UAS)

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

Description

The Custom Key Value Association API enables you to create, delete and retrieve the associations for Custom Key Value Targeting and supports both a generic search for all associations or details for only those that match specific search criteria.

Note: The Update operation is not supported directly. The update is supported via "configure" and is allowed to be called only in a programmatic way.

Creation and deletion of an association is based on the context. A context can be a "customkey."  Once the create and delete API are complete, they return the data from the database depending upon the context. So if the context used is "customkey" then the records would be retrieved using the custom key ids passed in the request body. Irrespective of the context, the request body syntax remains the same for delete and create operations.

For more information about UAS Account & Admin Services APIs, refer to Account & Admin Services (UAS)  

Supported Operations

                           

Method PathHTTP MethodDescriptionLink to Definition
/customvalues/customkeys/configurePOST

Create and associate the custom values for a given key.

If no custom key value is associated with a key, the key will be considered as "free form" and you can add values during targeting.

Configure Custom Key & Value Association
/customvalues/customkeys/{id}GETRetrieve a list of values associated with a custom key identifier.Retrieve values of a Custom Key
/customvalues/GET

Retrieve the details of all of the associations with all of the custom keys.

Retrieve a List of Custom Values

 

 

Configure Custom Key & Value Association

 

Overview

This API enables you to create and associate Custom Values to valid Custom Keys.

IMPORTANT NOTE: Configure will replace all of your existing custom values if they exist for the same key. In this case, you must provide all of the custom values if you would like to add additional values and keep the existing one as it is for a given key.

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

                               

Parameter NameTypeRequiredValidationsDescriptions
valueStringNoCan be a maximum of 255 characters and should be unique for a single custom key.A value for the Custom Key
customKeyNumericYesMust be available in the system.A Custom Key ID for the corresponding value
statusNumericNoShould be valid and exists. Status of the Custom Key Value Association.

Sample Request URL

https://api.pubmatic.com/v1/uas/customvalues/customkeys/configure 

 

Sample Request JSON

Adding Values to a Custom Key

    

[
    {
        "value": "25 - 35",
        "customKey": {
            "id": 1
        },
        "status": {
            "id": 1
        }
    },
    {
        "value": "55 - 65",
        "customKey": {
            "id": 1
        },
        "status": {
            "id": 1
        }
    }
]

Removing all Values from a Custom Key 

 

[{
    "customKey": {
        "id": 1
    }
}]

Sample Response JSONResponse

   

[
    {
        "value": "25 - 35",
        "customKey": {
            "id": 1,
            "name": "Age",
            "url": "http://$URI_PREFIX/phoenix/customkeys/1"
        },
        "status": {
            "id": 1,
            "name": "Active",
            "url": "http://$URI_PREFIX/phoenix/status/1"
        }
    },
    {
        "value": "55 - 65",
        "customKey": {
            "id": 1,
            "name": "Age",
            "url": "http://$URI_PREFIX/phoenix/customkeys/1"
        },
        "status": {
            "id": 1,
            "name": "Active",
            "url": "http://$URI_PREFIX/phoenix/status/1"
        }
    }
]

 

Retrieve values of a Custom Key

 

Overview

This API enables you to retrieve the details of all of the associations with all of the Custom Keys.

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.

 

Sample Request URL

https://api.pubmatic.com/v1/uas/customvalues/customkeys/1 

Response

Sample Response JSON

 

[
    {
        "value": "25 - 35",
        "customKey": {
            "id": 1,
            "name": "Age",
            "url": "http://$URI_PREFIX/phoenix/customkeys/1"
        },
        "status": {
            "id": 1,
            "name": "Active",
            "url": "http://$URI_PREFIX/phoenix/status/1"
        }
    }
]

 

 

Retrieve a List of Custom Values

 

Overview

This API enables you to retrieve a list of all custom values associated with your account across all Custom Keys. In the query, you can also apply supported dimensions, filters and sorting options to retrieve a list with a specific set of details according to your requirements.

Request

           

URIHTTP Method
https://$URI_/PREFIX/{apiVersion}/phoenix/customvalues/GET

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.

 

Sample Request URL

https://api.pubmatic.com/v1/uas/customvalues/ 

Response

Sample Response JSON

    

{
    "metaData": {
        "startIndex": 1,
        "totalRecords": 2,
        "endIndex": 2
    },
    "items": [
        {
            "value": "100",
            "customKey": {
                "id": 2,
                "name": "Height",
                "url": "http://$URI_PREFIX/phoenix/customkeys/2"
            },
            "status": {
                "id": 1,
                "name": "Active",
                "url": "http://$URI_PREFIX/phoenix/status/1"
            }
        },
        {
            "value": "25 - 35",
            "customKey": {
                "id": 1,
                "name": "Age",
                "url": "http://$URI_PREFIX/phoenix/customkeys/1"
            },
            "status": {
                "id": 1,
                "name": "Active",
                "url": "http://$URI_PREFIX/phoenix/status/1"
            }
        }
    ]
}
 

Sample URL for Generic Search

https://api.pubmatic.com/v1/uas/customvalues?dimensions=value

 

Sample Response JSON for Generic Search

 

{
    "metaData": {
        "startIndex": 1,
        "totalRecords": 2,
        "endIndex": 2
    },
    "items": [
        {
            "value": "100"
        },
        {
            "value": "25 - 35"
        }
    ]
}

Error Codes for Custom Key Value Association

 

Error Codes for Custom Key Value Associations

                                                     

Sr. No

Error Codes

Description

1.

MISSING_OR_INVALID_PARAMETER

This error message will occur when mandatory parameter is missing or invalid in the request.

e.g. Parameter customKey is missing.

2.

INVALID_DIMENSION

This error message will occur when requested dimension(s) is not supported.

Indicates that the dimension requested is invalid

3.

INVALID_SORT_KEY

This error message will occur when sort key is not found in requested dimension(s)

Indicates that the sort key requested is invalid.

4.

INVALID_FILTER_EXPRESSION

This error message will occur when filter expression invalid. Not able to parse filter expression(s).

Indicates that the filter key requested is invalid.

5.

PH_DUPLICATE_ENTRIES_FOUND

This error message will occur when attempting to configure duplicate values for a given custom key

Indicates a duplicate key value pair.

6.

PH_UNSUPPORTED_CUSTOM_VALUE

This error message will occur when attempting to configure invalid type of custom Value for a given custom key.

Indicates that value is not supported for the given custom key.

7.

PH_REACHED_LIMIT_OF_MAX_CUSTOM

This error message will occur when attempting to configure more than the allowed number of values for a given custom key. Currently at max 50 values can be associated with a given key.

8.PH_ATTEMPT_TO_ASSOCIATE_WITH_UNSUPPORTED
_STATUS_ENTITY_MSG
This error message will occur when trying to associate custom values with an archived custom key
9.PH_UNSUPPORTED_VALUE_MSGWhen the custom value is created/updated with any status except active.

 

 

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 9

Attachments

    Outcomes