Custom Key API (UAS)

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

Description

The Custom Key API enables you to create, update and retrieve account-level Custom Keys to be used for Custom Key Value Targeting on a Line Item.

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

Supported Operations

                                             

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

 

Create a Custom Key

 

Overview

This API enables you to create a Custom 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
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

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



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

 

Retrieve Details of a Custom Key

 

Overview

This API enables you to retrieve the details of an individual Custom 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.

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

 

Retrieve a List of Custom Keys

 

Overview

This API enables you to 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.

Refer to 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.
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/customkeys/ 

Response

Sample Response

    

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

Update a Custom Key

 

Overview

This API enables you to update a Custom Key. Only Description and Status can be updated. 

Status can be changed with the following transitions:

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

Once Status is set to Archived, it cannot be updated further.

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

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

 

Update (Patch) a Custom Key

 

Overview

This API enables you to perform a (partial) update of a Custom Key. Only Description and Status can be updated.

If the Status is "Archived" no attributes associated with the Custom Key can be updated.

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

Overview

This API enables you (delete) archive a Custom 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.

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_ENTITYThis error occurs when attempting to create a new Custom Key with the same name of a Custom Key within the same account that already exists.
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.

 

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 13

Attachments

    Outcomes