Page tree


Before using PubMatic APIs, first generate the API Token. For more information, see  Getting Started with PubMatic APIs .  

An ad unit group is a logical collection of similar ad units. Retrieve, create, update, and archive ad unit groups using the API methods described below.


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

Supported Operations

Method PathHTTP Method TypeDescriptionLink to Definition
                /adunitgroups/
              
POST
Creates an ad unit group for your accountCreate an Ad Unit Group
/adunitgroups/{id}
GET
Retrieves the details of a specific ad unit group for the requested ad unit group ID.Retrieve Details for an Ad Unit Group
/adunitgroups/
GET
Retrieves 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; for example, 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; that is, the status of the deleted ad unit group is changed from Active to Archived.

Delete an Ad Unit Group


Request Headers and Response Body Parameters

The following tables list all request headers and response body parameters used by the supported operations listed above.

Request Headers

Header name Type  Value Required Description
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, see Getting Started with PubMatic APIs.


Request Body Parameters

Parameter NameTypeRequiredValidationsDescription
account
NumericYes

Account should exist and be valid

Account associated with the ad unit group
name
StringYes

Name can be a maximum of 255 characters.

Name should be unique for your account.

ad unit group name should be descriptive.
description
StringNo

Description can be a maximum of 1024 characters.

Default is null.

Description to store more details for ad unit format.
adUnits
NumericYes
  • 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.

status
NumericYes

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
4 = Archived

user
NumericNoUser 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.


Operations and Samples

The following sections describe the line item API operations and provide sample code to demonstrate usage. Unless otherwise noted in the operation definition, each operation uses the request headers and request body parameters listed above.

Create an Ad Unit Group

This API lets you create an ad unit group for your account.

Request


Notes:

  • See Request Headers above for request header requirements.
  • See Request Body Parameters for parameters available to use in this request.

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

This API lets you retrieve details for a specific ad unit group.

Request

See Request Headers above for request header requirements.

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

This API lets you 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

See Request Headers above for request header requirements.

Request Sample URL

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

Response

Sample Response JSON

Returns a list of all ad unit groups associated with your account.


Update an Ad Unit Group

This API lets you create an ad unit group for your account. This API does a full replacement of the ad unit group.

Request


Notes:

  • See Request Headers above for request header requirements.
  • See Request Body Parameters for parameters available to use in this request.


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

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


Notes:

  • See Request Headers above for request header requirements.
  • See Request Body Parameters for parameters available to use in this request.


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

This API lets you delete (archive) an ad unit group for your account.

Request

See Request Headers above for request header requirements.

Request Sample URL

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

Response


Response returns True on successful archive; False on unsuccessful.


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.

⇧ Top