Macro API (UAS)

Document created by pubmatic-archivist on Mar 27, 2017Last modified by david.simerly on Aug 2, 2018
Version 12Show Document
  • View in full screen mode
Before using PubMatic APIs, first generate the API Token. For more information, refer to Getting Started with PubMatic APIs.

The Macro API queries the macro table and returns a list of non-deprecated macros supported by the Unified Ad Server.

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

Supported Operations

Service Name: /common/macro/

Method PathHTTP Method TypeDescriptionLink to Definition
/macro/{id}GETRetrieves the details of the macro for the Id providedRetrieve Details of a Macro
/macro/GET

Retrieves a list of all macros defined in the table.

You can apply supported dimensions, filters and sorting options by macro service to retrieve a list of macros with a specific set of details as needed.

Retrieve a list of Macros
/macro/?dimensions=name,description&
filters=id eq <macro_id>
GETRetrieves the details of the macro with the dimensions and filters used.Generic Search

 

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, see Getting Started with PubMatic APIs.

 

Response Body Parameters

Parameter NameTypeDescription
idIntegerUnique identifier of the macro.
nameStringName of the macro.
descriptionStringDescription about the macro.
categoryObjectMacro category object.

 

Operations and Samples

The following sections describe the Macro 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 a Macro

This API retrieves the details of a macro for the specified ID.

 

Request

URIHTTP Method
$URI_/PREFIX/common/macro/{id}
GET

See Request Headers above for request header requirements.

Sample Request URL

https://$URI_PREFIX/common/macro/1

 

Response

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

Sample Response JSON

{
"id": 1,
"name": "Ad Unit Id",
"description": "Replaced with Ad Unit Id where ad is served",
"catgory":
{
"id": 1
"name": "Ad Request"
}
}

 

Retrieve a List of Macros

This API retrieves a list of macros from Unified Ad Server.

 

Request

URIHTTP Method
$URI_/PREFIX/common/macro/
GET

See Request Headers above for request header requirements.

Sample Request URL

https://$URI_PREFIX/common/macro/

 

Response

There are no supported parameters for this operation.

Sample Response

Return a list of all macros available from Unified Ad Server.

 

This API retrieves a list of macros in the Unified Ad Server that match the filters and dimensions used in the search.

For more information on dimensions and filters, see Common Request Query Parameters.

Request

URIHTTP Method
$URI_/PREFIX/common/macro/?dimensions=name,description&filters=id eq <macro_id>
GET

See Request Headers above for request header requirements.

Sample Request URL

https://$URI_PREFIX/common/macro/?dimensions=name,description&filters=id eq 1

 

Response

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

Sample Response JSON

{
"metaData": {
"startIndex": 1,
"totalRecords": 1,
"endIndex": 1
},
"items": [
{
"name": "Escaped Ad Unit Url",
"description": "Replaced with escaped URL of the Ad Unit where the ad is served",
}
]
}

 

Error Codes for Macro API

Error CodeError Description
CC03_004Resource not found

 

Unified Ad Server References

 

⇧ Top

Attachments

    Outcomes