Page tree


The Custom Key API lets you create, update and retrieve account-level Custom Keys to be used for Custom Key Value Targeting on a Line Item. Set custom values using the Custom Key API itself and create, update and delete operations are permitted on custom values.

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

Supported Operations

Service Name: /customkeys/

Method PathHTTP Method TypeDescriptionLink to Definition
/customkeys/POSTThis API method will create only one Custom Key per requestCreate a Custom Key
/customkeys/{id}GETRetrieve the Custom Key details using Custom Key IDRetrieve Details of a Custom Key
/customkeys/GET

Retrieve a list of Custom Keys associated with your account. 

Using this API, you can apply dimensions, filter criteria and sorting option to retrieve a list of records.

Retrieve a List of Custom Keys
/customkeys/{id}PUT

This API method updates a single custom key

Description and Status can be updated using this method. No other fields, once set, cannot be updated.

Update a Custom Key
/customkeys/{id}PATCH

This API method does a partial update on a Custom Key.

Description and Status can be updated using this method. No other fields, once set, cannot be updated.

Update (Patch) a Custom Key
/customkeys/{id}DELETEThis API method deletes (archives) a Custom Key.Delete a Custom Key


Custom Values Configuration

  • It is possible to remove the existing custom values from the custom key by passing null or [] as values.
  • The values object is not used as a searchable dimension. It is always returned in create / update / get / search customKey responses.
  • Updating custom values will remove all existing data and write the data in request.

Create a Custom Key

This API lets you create a Custom Key.

Request   



Request Headers

Header nameType ValueRequiredDescription
Content-TypeStringapplication/jsonYesMedia type for request.
AuthorizationStringBearer ${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
accountNumericYes

Account must exist and be valid.

The Account of the Publisher

nameStringYes

Can be a maximum of 50 characters and should be unique at the account level.

Can create a custom key with a name that is the same as that of an archived custom key at the account level.

The name cannot have spaces within itself.

Name for the Custom Key
descriptionStringNoCan be a maximum of 255 characters.Custom Key description
typeNumericNoType should be valid

Type of the Custom Key. The following are valid for Custom Keys:

1=Numeric

2=Text

statusNumericNo
  • Should be valid and should exist.
  • The Default is "Active" for newly created key if not provided.
  • The status can be updated to Inactive and Archived.
  • Customkey is created in default active status.

Status of the Custom Key. The following are valid for  Custom Keys:

1= Active

2=Inactive

4= Archived

valuesList<String>No
  • Can be null/empty/valid list of values.
  • Value can be of maximum of 255 characters.
  • Value should be unique for a single custom key.

List of values set for the custom key.


Sample Request URL

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


Sample Request JSON

{
    "account": {
        "id": 118385
    },
     "name": "Age",
    "description": "Age of person",
    "type": 1,
    "status": {
        "id": 1
    },
    "values": [
          "30",
          "25"
     ]
}


‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Response

Sample Response JSON


{
    "id": 1,
    "account": {
        "id": 118385,
        "name": "PubMatic Inc.",
        "url": "http://$URI_PREFIX/phoenix/accounts/1"
    },
     "name": "Age",
    "description": "Age of person",
    "type": 1,
    "status": {
        "id": 1,
        "name": "Active",
        "url": "http://$URI_PREFIX/phoenix/status/1"
    },
    "values": [
          "30",
          "25"
     ]
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Retrieve Details of a Custom Key

This API lets you retrieve the details of an individual Custom Key.

Request


Request Headers

Header nameType ValueRequiredDescription
Content-TypeStringapplication/jsonYesMedia type for request.
AuthorizationStringBearer ${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/customkeys/1


Response

Sample Response JSON

{
    "id": 1,
    "account": {
        "id": 118385,
        "name": "PubMatic Inc.",
        "url": "http://$URI_PREFIX/phoenix/accounts/1"
    },
       "name": "Age",
    "description": "Age of person",
    "type": 1,
    "status": {
        "id": 1,
        "name": "Active",
        "url": "http://$URI_PREFIX/phoenix/status/1"
    },
    "values": [
          "30",
          "25"
     ]
 }‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍


Retrieve a List of Custom Keys

This API lets you retrieve a list of Custom Keys. In the query, you can also apply supported dimensions, filters and sorting options to retrieve a list of Custom Keys with a specific set of details according to your requirements.


See Common Request Query Parameters for more information about using dimensions, filters and sorting.

Request


Request Headers

Header nameType ValueRequiredDescription
Content-TypeStringapplication/jsonYesMedia type for request.
AuthorizationString${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/customkeys/

Response

Sample Response


The response will return all Custom Keys associated with your account.


Update a Custom Key

This API lets you update a Custom Key.

You can update only Description and Status.

C hange Status with the following transitions:


  • Active --> Inactive
  • Active --> Archived
  • Inactive --> Active
  • Inactive --> Archived


Status becomes permanently read-only after it has been set to Archived.

Request



Request Headers

Header nameType ValueRequiredDescription
Content-TypeStringapplication/jsonYesMedia type for request.
AuthorizationStringBearer ${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
accountNumericYes

Account must exist and be valid.

The Account of the Publisher

nameStringYes

Can be a maximum of 50 characters and should be unique at the account level.

Can create a custom key with a name that is the same as that of an archived custom key at the account level.

The name cannot have spaces within itself.

Name for the Custom Key
descriptionStringNoCan be a maximum of 255 characters.Custom Key description
typeNumericNoType should be valid

Type of the Custom Key. The following are valid for Custom Keys:

1=Numeric

2=Text

statusNumericNoShould be valid and should exist. The Default is "Active" for newly created key if not provided.

Status of the Custom Key. The following are valid for  Custom Keys:

1= Active

2=Inactive


Sample Request URL

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


Sample Request JSON

{
    "account": {
        "id": 118385
    },
    "id": 1,
    "name": "Age",
    "description": "Age of the customers",
    "type": 1,
    "status": {
        "id": 1
    },
    "values": [
          "22",
          "45"
     ]
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍


Response

Sample Response JSON

{
    "id": 1,
    "name": "Age",
    "description": "Age of the customers",
    "account": {
        "id": 118385,
        "name": "PubMatic Inc.",
        "url": "http://$URI_PREFIX/phoenix/accounts/1"
    },
    "type": 1,
    "status": {
        "id": 1,
        "name": "Active",
        "url": "http://$URI_PREFIX/phoenix/status/1"
    },
    "values": [
          "22",
          "45"
     ]
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

 

Update (Patch) a Custom Key

This API lets you perform a (partial) update of a Custom Key.

You can update only Description and Status.
Status becomes permanently read-only after it has been set to Archived.

Request



Request Headers

Header nameType ValueRequiredDescription
Content-TypeStringapplication/jsonYesMedia type for request.
AuthorizationStringBearer ${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
accountNumericYes

Account must exist and be valid.

The Account of the Publisher

nameStringYes

Can be a maximum of 50 characters and should be unique at the account level.

Can create a custom key with a name that is the same as that of an archived custom key at the account level.

The name cannot have spaces within itself.

Name for the Custom Key
descriptionStringNoCan be a maximum of 255 characters.Custom Key description
typeNumericNoType should be valid

Type of the Custom Key. The following are valid for Custom Keys:

1=Numeric

2=Text

statusNumericNoShould be valid and should exist. The Default is "Active" for newly created key if not provided.

Status of the Custom Key. The following are valid for  Custom Keys:

1= Active

2=Inactive


Sample Request URL

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


Sample Request JSON

{
"description": "Age of the customers"
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍


Response

Sample Response JSON

{
    "id": 1,
    "name": "Age",
    "description": "Age of the customers",
    "account": {
        "id": 118385,
        "name": "PubMatic Inc.",
        "url": "http://$URI_PREFIX/phoenix/accounts/1"
    },
    "type": 1,
    "status": {
        "id": 1,
        "name": "Active",
        "url": "http://$URI_PREFIX/phoenix/status/1"
    }

 

Delete a Custom Key

This API lets you archive (delete) a Custom Key.

Request



Request Headers

Header nameType ValueRequiredDescription
Content-TypeStringapplication/jsonYesMedia type for request.
AuthorizationStringBearer ${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/customkeys/1

Response

Sample Response

true‍‍‍‍‍‍‍‍‍‍

Error Codes for Custom Key API

Sr. NoError CodesDescription
1.PH_MISSING_OR_INVALID_PARAMETER

This error occurs when: 

  • Requested details for a Custom Key with ID that does not exist or is invalid
  • Didn't pass the "type" attribute along with valid value.
2.PH_DUPLICATE_ENTITY

This error occurs when a user tries to create a new Custom Key with the same name of the Custom Key within a single account existing in database.


This error also occurs when attempting to set duplicate values for a given custom key

3.PH_ATTEMPT_TO_UPDATE_SEALED_VALUE

This error occurs when attempting to update a field that cannot be updated further once set at the time of creation. This can occur for the following:

  • Name
  • Type
  • Status (once archived)
4.PH_ATTEMPT_TO_UPDATE_SEALED_VALUE_ACCOUNT_ID This error occurs when attempting to update the account ID.
5.PH_PARAMETER_VALUE_TOO_LARGE

This error occurs when attempting to use more characters than are allowed for a field. This can occur for the following fields:

  • Name (Max limit= 50)
  • Description (Max limit=255)
6.PH_UNSUPPORTED_VALUE

This error occurs when attempting to update the status with an ID that is not supported for Custom Keys.

Supported statuses include: Active, Inactive, Archived

7.PH_PARAMETER_SPACE_NOT_ALLOWEDThis error occurs if the custom parameter name contains spaces in it.
8.PH_ATTEMPT_TO_UPDATE_RESTRICTED_FIELD_IN_STATUSThis error occurs if a user tries to alter any parameter for a deleted key.
9.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.

10.PH_REACHED_LIMIT_OF_MAX_CUSTOM

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

11.PH_ATTEMPT_TO_ASSOCIATE_WITH_UNSUPPORTED_STATUS_ENTITY_MSG

The error message occurs when trying to associate custom values with an archived custom keys.

⇧ Top