Native API (UAS)

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

Description

The Native API provides and stores information relevant to the native advertising format. Native Meta Data APIs are exposed under the "/common" endpoint, whereas template creation API is an independent micro service under the Unified Ad Server, exposed under "/phoenix-nativeads/nativeconfig."

For more information about UAS Native Template Services APIs, refer to Native Template Services (UAS)

Supported Operations

Service Name: /nativeconfig/

                                       

Method PathHTTP Method TypeDescriptionLink to Definition

/phoenix-nativeads/nativeconfig/
POSTCreates a Native TemplateCreate a Native Template
/phoenix-nativeads/nativeconfig/{id}GETRetrieves a Unified Ad Server Native Template using a native template id.Retrieve the Details of a Native Template
/phoenix-nativeads/nativeconfig/GET

Retrieve a list of Native Templates associated with your account.

In the query, you can also apply supported dimensions, filters and sorting options to retrieve a list with a specific set of details according to your requirements.

Retrieve a List of Native Templates
/phoenix-nativeads/nativeconfig/requestJSON/GETRetrieve an OpenRTB standard request JSON for a config specified by id.Retrieve an OpenRTB Request JSON for a Specific Native Template

/phoenix-nativeads/nativeconfig/{id}
DELETEDelete (archive) a Unified Ad Server Native TemplateDelete a Native Template

 

 

Create a Native Template

 

Overview

This API enables you to create a Native Template.

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
nameStringYes

Can be a maximum of 50 characters containing letters, numbers, dashes, hyphens, periods, asterisks and colons.

Should be unique for the Native Template ad an account level.

If no name is provided then the template will be created using a default name: "PhoenixNativeConfig-<account_id>-<random_number>"

Name of the Native Template

layoutIdNumericYesShould be valid and exist in the system

Layout Id of the Native Template. To get the list of layout ids used, use the common endpoint:

/common/nativetemplate

The following are valid Layout Ids:

                                   
layout idTemplate Name
501Custom Template
1Content Wall Template
2App Wall Template
3New Feed Template
4Chat List Template
5Carousel Template
6Content Stream Template

For more information about layout id, please refer to OpenRTB Native Ads Specifications

iabAdUnitIdNumericNoOptional

Adunit id for the ad for Custom iabAdUnitId=5; for other layouts, no adunit id is required.

For more information, please refer to OpenRTB Native Ads Specifications

isDeletedNumericNoNot required in request body. This will be present only in the response.

Determines whether the native template is deleted.

               
ValueDescription
Not Deleted
1Deleted
accountIdNumericYesAccount Id should be valid and exist in the system.Native Template account Id
assetsArray of Native Template Asset ObjectsYesMandatory

The assets of the Native Template. These assets define the structure of the Native Template. While creating a Native Creative, which uses a particular Native Template, these assets are validated against the creative assets of that Native Creative.

For additional information, please refer to the Creative API.

The following are valid types and subtypes of assets:

                                                                                             
typeIdsubTypeIdname
1-Title
21Icon Image
22Logo Image
23Main Image
31Sponsored Data
32Desc Data
33Rating Data
34Likes Data
35Downloads Data
36Price Data
37Salesprice Data
38Phone Data
39Address Data
310Desc2 Data
311DisplayUrl Data
312CtaText Data
4-Video

Note: Currently the Video asset type is not being used in the Unified Ad Server.

Please refer to OpenRTB Native Ads Specification for more details on the Asset Object.

Additional Request Body Parameters under assets parameter for Native Template

                                                                  

Parameter NameTypeRequiredValidationDescription
idNumericRead OnlyAuto-generated by the APIThis is auto-generated by the API for internal purposes.
assetIdNumericRead OnlyAuto-generated by the API

Unique asset ID, assigned by PubMatic. 

This is auto-generated by the API within the context of the template being created. AssetId will be used by the Creative API as a reference identifier during the configuration of the creative assets of the Native Creative for the selected template.

typeIdNumericYesShould be valid and exist in the system.Asset type identifier what will be added in the template. A list of asset types can be retrieved using the Native Asset Type API.
typeNameStringRead Only Asset type name of the asset.
subTypeIdNumericYes (Only required when the asset type has a subType. e.g., Image & Data Type.)Should be valid and exist in the systemAsset SubType of the asset. (Refer to typeId and subTypeId in the table above.)
isRequiredNumericNo

Default Value = 0 for custom Native Templates.

Other standard templates should follow IAB protocol. 

isRequired flag is used to determine whether the given asset is required or not.

isDeletedNumericNoOptional

Determines whether the asset is deleted.

               
ValueDescription
0Not Deleted
1Deleted
 
propertiesList of properties objectsYesValid properties should be used.

Properties of a particular asset.

Example: To use a Main Image asset, provide properties such as height, width, mime type, etc.

    

"properties": [{
            "name": "w",
            "value": 150
        }, {
            "name": "h",
            "value": 150
        }, {
            "name": "mime",
            "value": "image/png"
        }]

This example provides 3 properties:

  1. Width (w) whose value is 150
  2. Height (h) whose value is 150
  3. Mime Type (mime) whose value is image/png

 

Sample Request URL

https://api.pubmatic.com/v1/uas-nativeads//nativeconfig/ 

Sample JSON Request

    

{
    "accountId": 118385,
    "name": "Native Template",
    "layoutId": 3,
    "assets": [{
        "typeId": 1,
        "properties": [{
            "name": "len",
            "value": 100
        }],
        "isRequired": 1
    }, {
        "typeId": 2,
        "subTypeId": 1,
        "properties": [{
            "name": "w",
            "value": 150
        }, {
            "name": "h",
            "value": 150
        }, {
            "name": "mime",
            "value": "image/png"
        }],
        "isRequired": 1
    }, {
        "typeId": 3,
        "subTypeId": 3,
        "properties": [{
            "name": "len",
            "value": 10
        }],
        "isRequired": 1
    }, {
        "typeId": 3,
        "subTypeId": 12,
        "properties": [{
            "name": "len",
            "value": 50
        }],
        "isRequired": 1
    }]
}

Response

Sample Response JSON

    

{
    "id": 247,
    "name": "Native Template",
    "layoutId": 3,
    "accountId": 118385,
    "iabAdUnitId": 0,
    "isDeleted": 0,
    "assets": [{
        "id": 862,
        "assetId": 1,
        "typeId": 1,
        "typeName": "title",
        "subTypeId": 0,
        "isRequired": 1,
        "isDeleted": 0,
        "properties": [{
            "id": 1405,
            "configId": 862,
            "name": "len",
            "value": "100",
            "isDeleted": 0
        }],
        "userDefinedAsset": false
    }, {
        "id": 863,
        "assetId": 2,
        "typeId": 2,
        "typeName": "image",
        "subTypeId": 1,
        "isRequired": 1,
        "isDeleted": 0,
        "properties": [{
            "id": 1406,
            "configId": 863,
            "name": "w",
            "value": "150",
            "isDeleted": 0
        }, {
            "id": 1407,
            "configId": 863,
            "name": "h",
            "value": "150",
            "isDeleted": 0
        }, {
            "id": 1408,
            "configId": 863,
            "name": "mime",
            "value": "image/png",
            "isDeleted": 0
        }],
        "userDefinedAsset": false
    }, {
        "id": 864,
        "assetId": 3,
        "typeId": 3,
        "typeName": "data",
        "subTypeId": 3,
        "isRequired": 1,
        "isDeleted": 0,
        "properties": [{
            "id": 1409,
            "configId": 864,
            "name": "len",
            "value": "10",
            "isDeleted": 0
        }],
        "userDefinedAsset": false
    }, {
        "id": 865,
        "assetId": 4,
        "typeId": 3,
        "typeName": "data",
        "subTypeId": 12,
        "isRequired": 1,
        "isDeleted": 0,
        "properties": [{
            "id": 1410,
            "configId": 865,
            "name": "len",
            "value": "50",
            "isDeleted": 0
        }],
        "userDefinedAsset": false
    }]
}

Retrieve the Details of a Native Template

Overview

This API enables you to retrieve details for a Native Template.

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.

Sample Request URL

https://api.pubmatic.com/v1/uas-nativeads//nativeconfig/247 

Response

Sample Response JSON

    

{
    "id": 247,
    "name": "Native Template",
    "layoutId": 3,
    "accountId": 118385,
    "iabAdUnitId": 0,
    "isDeleted": 0,
    "assets": [{
        "id": 862,
        "assetId": 1,
        "typeId": 1,
        "typeName": "title",
        "subTypeId": 0,
        "isRequired": 1,
        "isDeleted": 0,
        "properties": [{
            "id": 1405,
            "configId": 862,
            "name": "len",
            "value": "100",
            "isDeleted": 0
        }],
        "userDefinedAsset": false
    }, {
        "id": 863,
        "assetId": 2,
        "typeId": 2,
        "typeName": "image",
        "subTypeId": 1,
        "isRequired": 1,
        "isDeleted": 0,
        "properties": [{
            "id": 1406,
            "configId": 863,
            "name": "w",
            "value": "150",
            "isDeleted": 0
        }, {
            "id": 1407,
            "configId": 863,
            "name": "h",
            "value": "150",
            "isDeleted": 0
        }, {
            "id": 1408,
            "configId": 863,
            "name": "mime",
            "value": "image/png",
            "isDeleted": 0
        }],
        "userDefinedAsset": false
    }, {
        "id": 864,
        "assetId": 3,
        "typeId": 3,
        "typeName": "data",
        "subTypeId": 3,
        "isRequired": 1,
        "isDeleted": 0,
        "properties": [{
            "id": 1409,
            "configId": 864,
            "name": "len",
            "value": "10",
            "isDeleted": 0
        }],
        "userDefinedAsset": false
    }, {
        "id": 865,
        "assetId": 4,
        "typeId": 3,
        "typeName": "data",
        "subTypeId": 12,
        "isRequired": 1,
        "isDeleted": 0,
        "properties": [{
            "id": 1410,
            "configId": 865,
            "name": "len",
            "value": "50",
            "isDeleted": 0
        }],
        "userDefinedAsset": false
    }]
}

 

Retrieve a List of Native Templates

 

Overview

This API enables you to retrieve a list of Native Templates. 

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.

 

Refer to Common Request Query Parameters for more information about using dimensions, filters and sorting, 
Using this API, you can apply dimensions, filter criteria and sorting option to retrieve a list of records.

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.

Sample Request URL

https://api.pubmatic.com/v1/uas-nativeads//nativeconfig/ 

Response

Sample Response

This will return all native templates associated with your account.

Sample Request with Generic Search URL

https://api.pubmatic.com/v1/uas-nativeads/nativeconfig?filters=id eq <specific native template id>

Sample Generic Search Response    

This will return native templates in your account that match the specified conditions.

 

Retrieve an OpenRTB Request JSON for a Specific Native Template

Overview

This API enables you to retrieve an OpenRTB Request JSON for a Specific Native Template

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.

Sample Request URL

https://api.pubmatic.com/v1/uas-nativeads/nativeconfig/247/requestJSON/ 

Response

Sample Response JSON

    

{
    "layout": 501,
    "accountId": 94727,
    "assets": [
        {
            "id": 1,
            "required": 0,
            "title": {
                "len": 100
            }
        },
        {
            "id": 2,
            "required": 0,
            "title": {
                "len": 100
            }
        },
        {
            "id": 3,
            "required": 0,
            "title": {
                "len": 100
            }
        }
    ]
}

 

Delete a Native Template

Overview

This API enables you to delete (archive) a list of Native Templates. 

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.

Sample Request URL

http://api.pubmatic.com/v1/uas-nativeads/nativeconfig/247 

Response

Sample Response    


[{
    "success": "Records Deleted Successfully with Config ID 247"
}]

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