Macro API (UAS)

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

Description

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

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

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

 

Retrieve Details of a Macro

Overview

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

Request

           

URIHTTP Method
$URI_/PREFIX/common/macro/{id}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.

Sample Request URL

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

Response

Response Body Parameters

                            

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

Sample Response JSON


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

 

Retrieve a list of Macros

Overview

This API retrieves a list of macros in the Unified Ad Server.

Request

           

URIHTTP Method
$URI_/PREFIX/common/macro/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.

Sample Request URL

https://$URI_PREFIX/common/macro/

Response

Response Body Parameters

                            

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

Sample Response

    

It will return a list of all macros available in the Unified Ad Server.

Macro API Generic Search

Overview

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, refer to Common Request Query Parameters.

Request

           

URIHTTP Method
$URI_/PREFIX/common/macro/?dimensions=name,description&filters=id eq <macro_id>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.

Sample Request URL

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

Response

Response Body Parameters

                            

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

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

Attachments

    Outcomes