Ad Unit Group API (UAS)

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

Description

An Ad Unit Group is a logical collection of similar Ad Units. You can retrieve, create, update and archive ad unit groups using these API methods.

For more information about UAS Inventory Management Services APIs, refer to Inventory Management Services (UAS) 

Supported Operations

                                             

Method PathHTTP Method TypeDescriptionLink to Definition
/adunitgroups/POSTCreates an Ad Unit Group for your accountCreate an Ad Unit Group
/adunitgroups/{id}GETRetrieves the details of a specific Ad Unit Group for the requested Ad Unit Group ID.Retrieve Details for an Ad Unit Group
/adunitgroups/GETRetrieves the list of Ad Unit Groups associated with your account. You can apply dimensions, filters, and sort options to fetch a list of Ad Unit Groups with specific details as needed.Retrieve a List of Ad Unit Groups
/adunitgroups/{id}PUT

Update a single Ad Unit Group (transactional).

This operation performs a full update. If the request does not contain a value for an attribute, it will be set to NULL/default value. If the parameter is mandatory, however, it will fail and the Ad Unit Group will be updated. 

Ensure you are passing all the required attributes with the required values.

The Ad Unit group cannot be updated to any status or by any parameter once it is moved to archive state.

Update an Ad Unit Group
/adunitgroups/{id}PATCH

Performs a patch of an ad unit group, e.g., to change only the status of an Ad Unit Group.

Currently, this method can only be used to update description and status of an Ad Unit Group.

The Ad Unit group cannot be updated to any status or by any parameter once it is moved to archive state.

Note: PATCH is different than a PUT, as a PUT is a full replacement of the object and PATCH only updates a specific attribute of the object.

Update (Patch) an Ad Unit Group
/adunitgroups/{id}DELETE

Delete an Ad Unit Group.

Note: This is a soft delete, i.e., the status of the deleted Ad Unit Group is changed from Active to Archived.

Delete an Ad Unit Group

 

Create an Ad Unit Group

 

Overview

This API enables you to create an Ad Unit Group for your account.

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

Account should exist and be valid

Account associated with the Ad Unit Group
nameStringYes

Name can be a maximum of 255 characters.

Name should be unique for your account.

Ad Unit Group name should be descriptive.
descriptionStringNo

Description can be a maximum of 1024 characters.

Default is null.

Description to store more details for ad unit format.
adUnitsNumericYes
  • Ad Units should exist in the system.
  • Account id of Ad Units and Ad Unit Group should be the same.
  • There should be at least one Ad Unit associated with the Ad Unit Group. 
  • Cannot associate an archived Ad Unit if with an Ad Unit Group.
  • An associated Ad Unit, if updated to archived status, should not be validated during an update operation of other entities. 

Ad Units that will be added to the Ad Unit Group.

You can create/edit/retrieve a list of Ad Units using the Ad Unit API.

statusNumericYes

Status should exist and be valid.

Default is "Active" for newly created Ad Unit Group if status is not provided.

Archive is the last status. It cannot be changed once in archive state.

Ad Unit Group Status.

You can retrieve a list of statuses using the Status API.

The following statuses are supported for an Ad Unit:

1 = Active
2 = Inactive
3 = Archived

userNumericNoUser ID of the user who is creating this Ad Unit Group.

User who is creating  this particular AD Unit Group.

You can create/edit/retrieve a list of Operational User details using the User API.

Request Sample URL

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

Sample Request JSON

{
    "account": {
        "id": 118385
    },
    "name": "US_Mobile_Sports_Mobile_Inventory",
    "description": "Ad Unit Group contains all Mobile Ad Units",
    "adUnits": [{
        "id": 896
    }],
    "status": {
        "id": 1
    }
}

 

Response

Sample Response JSON

{
  "id": 56,
  "name": "US_Mobile_Sports_Mobile_Inventory",
  "description": "Ad Unit Group contains all Mobile Ad Units",
  "account": {
    "id": 118385,
    "url": "http://api.pubmatic.com/v1/uas/"
  },
  "status": {
    "id": 1,
    "name": "Active",
    "url": "http://api.pubmatic.com/v1/uas/status/1"
  },
  "user": {
    "id": 18280,
    "url": "http://api.pubmatic.com/v1/uas/users/18280"
  },
  "adUnits": [
    {
      "id": 896
    }
  ]
}

Retrieve Details for an Ad Unit Group

 

Overview

This API enables you to retrieve details for a specific Ad Unit Group.

 

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

https://api.pubmatic.com/v1/uas/adunitgroups/56 

Response

Sample Response JSON

    

{
    "id": 56,
    "name": "US_Mobile_Sports_Mobile_Inventory-New",
    "description": "Ad Unit Group contains all Mobile Ad Units",
    "account": {
        "id": 118385,
        "url": "http://api.pubmatic.com/v1/uas/"
    },
    "status": {
        "id": 1,
        "name": "Active",
        "url": "http://api.pubmatic.com/v1/uas/status/1"
    },
    "user": {
        "id": 18280,
        "url": "http://api.pubmatic.com/v1/uas/users/18280"
    },
    "adUnits": [{
        "id": 896
    }]
}

 

Retrieve a List of Ad Unit Groups

Overview

This API enables you to retrieve details for a specific Ad Unit Group. In the query, you can also apply supported dimensions, filters and sorting options to retrieve a list of Ad Units with a specific set of details according to your requirements.

Request

           

URIHTTP Method
https://$URI_/PREFIX/{apiVersion}/phoenix/adunitgroups/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.

Request Sample URL

https://$URI_PREFIX/{apiVersion}/phoenix/adunitgroups/

Response

Sample Response JSON

    

The API will return a list of all Ad Unit Groups associated with your account.

 

Update an Ad Unit Group

Overview

This API enables you to create an Ad Unit Group for your account. This API does a full replacement of the Ad Unit Group.

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

Account should exist and be valid

Account associated with the Ad Unit Group
nameStringYes

Name can be a maximum of 255 characters.

Name should be unique for your account.

Ad Unit Group name should be descriptive.
descriptionStringNo

Description can be a maximum of 1024 characters.

Default is null.

Description to store more details for ad unit format.
adUnitsNumericYes
  • Ad Units should exist in the system.
  • Account id of Ad Units and Ad Unit Group should be the same.
  • There should be at least one Ad Unit associated with the Ad Unit Group. 
  • Cannot associate an archived Ad Unit if with an Ad Unit Group.
  • An associated Ad Unit, if updated to archived status, should not be validated during an update operation of other entities. 

Ad Units that will be added to the Ad Unit Group.

You can create/edit/retrieve a list of Ad Units using the Ad Unit API.

statusNumericYes

Status should exist and be valid.

Default is "Active" for newly created Ad Unit Group if status is not provided.

Archive is the last status. It cannot be changed once in archive state.

Ad Unit Group Status.

You can retrieve a list of statuses using the Status API.

The following statuses are supported for an Ad Unit:

1 = Active
2 = Inactive
3 = Archived

userNumericNoUser ID of the user who is creating this Ad Unit Group.

User who is creating  this particular AD Unit Group.

You can create/edit/retrieve a list of Operational User details using the User API.

Request Sample URL

https://api.pubmatic.com/v1/uas/adunitgroups/56 

Sample Request JSON

    

{
    "account": {
        "id": 118385
    },
    "name": "US_Mobile_Sports_Mobile_Inventory",
    "description": "Ad Unit Group contains all Mobile Ad Units",
    "adUnits": [{
        "id": 896
    }],
    "status": {
        "id": 1
    }
}

Response

Sample Response JSON

    

{
  "id": 56,
  "name": "US_Mobile_Sports_Mobile_Inventory",
  "description": "Ad Unit Group contains all Mobile Ad Units",
  "account": {
    "id": 118385,
    "url": "http://api.pubmatic.com/v1/uas/"
  },
  "status": {
    "id": 1,
    "name": "Active",
    "url": "http://api.pubmatic.com/v1/uas/status/1"
  },
  "user": {
    "id": 18280,
    "url": "http://api.pubmatic.com/v1/uas/users/18280"
  },
  "adUnits": [
    {
      "id": 896
    }
  ]
}

 

Update (Patch) an Ad Unit Group

Overview

Updates only the requested attribute for an Ad Unit Group. This API performs a PATCH of the Ad Unit Group, not a full replacement of the Ad Unit Group.

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

Account should exist and be valid

Account associated with the Ad Unit Group
nameStringYes

Name can be a maximum of 255 characters.

Name should be unique for your account.

Ad Unit Group name should be descriptive.
descriptionStringNo

Description can be a maximum of 1024 characters.

Default is null.

Description to store more details for ad unit format.
adUnitsNumericYes
  • Ad Units should exist in the system.
  • Account id of Ad Units and Ad Unit Group should be the same.
  • There should be at least one Ad Unit associated with the Ad Unit Group. 
  • Cannot associate an archived Ad Unit if with an Ad Unit Group.
  • An associated Ad Unit, if updated to archived status, should not be validated during an update operation of other entities. 

Ad Units that will be added to the Ad Unit Group.

You can create/edit/retrieve a list of Ad Units using the Ad Unit API.

statusNumericYes

Status should exist and be valid.

Default is "Active" for newly created Ad Unit Group if status is not provided.

Archive is the last status. It cannot be changed once in archive state.

Ad Unit Group Status.

You can retrieve a list of statuses using the Status API.

The following statuses are supported for an Ad Unit:

1 = Active
2 = Inactive
3 = Archived

userNumericNoUser ID of the user who is creating this Ad Unit Group.

User who is creating  this particular AD Unit Group.

You can create/edit/retrieve a list of Operational User details using the User API.

Request Sample URL

https://api.pubmatic.com/v1/uas/adunitgroups/56 

Sample Request JSON

    

{
    "adUnits": [{
        "id": 896
    },
    {
        "id": 923
    }],
    "status": {
        "id": 2
    }
}

Response

Sample Response JSON

    

{
  "id": 56,
  "name": "US_Mobile_Sports_Mobile_Inventory-New",
  "description": "Ad Unit Group contains all Mobile Ad Units",
  "account": {
    "id": 118385,
    "url": "http://api.pubmatic.com/v1/uas/"
  },
  "status": {
    "id": 2,
    "name": "Inactive",
    "url": "http://api.pubmatic.com/v1/uas/status/2"
  },
  "user": {
    "id": 18280,
    "url": "http://api.pubmatic.com/v1/uas/users/18280"
  },
  "adUnits": [
    {
      "id": 896
    },
    {
      "id": 923
    }
  ]
}

Delete an Ad Unit Group

Overview

This API enables you to delete (archive) an Ad Unit Group for your account.

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

https://api.pubmatic.com/v1/uas/adunitgroups/56 

Response

    

Response returns True if archive is successful; False if not successful.

Error Codes for Unified Ad Server Ad Unit Group API

                                      

Sr. No.Error CodesDescription
1.PH_MISSING_OR_INVALID_PARAMETER

This error occurs when a mandatory field is missing or its value is not value (not present in the database).

This error can occur for the following parameters:

  • Ad Unit Group Id
  • Account Id
  • Name
  • Status
2.PH_DUPLICATE_ENTITYThis error can occur for the 'name' parameter. 
3. PH_PARAMETER_VALUE_TOO_LARGE

It can occur in the following parameters:

  • Ad Unit Group Id
  • Name
  • Description
  • Status
  • Account
4.PH_ATLEAST_ONE_AD_UNIT_REQUIREDThis error occurs when you do not provide an Ad Unit in the Ad Unit List.
5.PH_UNSUPPORTED_VALUE

This error occurs when you provide unsupported status for the Ad Unit Group.

Supported statuses for Ad Unit Group include:

  • Active
  • Inactive
  • Archived
6.PH_ATTEMPT_TO_ASSOCIATE_WITH_UNSUPPORTED_STATUS_ENTITYThis error occurs when you select an archived adUnit for association.

 

 

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

Attachments

    Outcomes