Page tree

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

The Macro Category API retrieves Macro categories used by the Unified Ad Server.  

For more information about UAS Macros, see Unified Ad Server Macros

Supported Operations

Service Name: /common/macrocategory/

Method PathHTTP Method TypeDescriptionLink to Definition

Retrieves the details of the macro category for the Id provided. The following are supported macro categories:

1Ad Request Macros
2Ad Response Macros
3Standard Macros
4Location Macros
5Mobile Device Macros
6Custom Macros

You can create and add custom macros by prefixing with %%VAR_<Custom Key Name >%%. You can retrieve the available custom key for your account using the Custom Key API.

Unified Ad Server replaces custom macros when it receives the key and value in the ad request and finds an exact match (it is case sensitive).

Retrieve details of Macro Category

Retrieves a list of supported macro categories supported by the Unified Ad Server. You can apply supported dimensions, filters, and sorting options to retrieve a list of macro categories with a specific set of details as needed.

Retrieve a list of Macro Categories

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

Response Body Parameters

Parameter NameTypeDescription
idIntegerUnique identifier of the macro category
nameStringName of the macro category
descriptionStringDescription for the macro category

Operations and Samples

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

Retrieve Details of Macro Category

This API retrieves the details of a macro category for the specified Id.



See Request Headers above for request header requirements.

Sample Request URL



See Response Body Parameters above for the list of parameters supported by this operation.

Sample Response JSON

  "id": 1,
  "name": "Ad Request Macros",
  "description": "Macros related to Ad Request "

Retrieve a List of Macro Categories

This API retrieves a list of macro categories supported by the Unified Ad Server.


See Request Headers above for request header requirements.


There are no supported parameters for this response.

Sample Request URL


Sample Response 

It will return a list of all macro categories supported by the Unified Ad Server.

Error Codes for Macro Category API

Error CodeError Description
CC03_004Resource not found


⇧ Top