Page tree


Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Reverted from v. 5

Anchor
top
top
Table of Contents
indent20px
stylenone


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

Description

Line Item Creative Association API enables you to create, delete and retrieve creatives associated with a line item. We can also retrieve all Line Items associated with a Creative.


Configuration of associations is based on the context and it overwrites the previous associations in between Line Item and Creatives. A context can be either "lineItems" or "creatives". Once we configured the associations it returns the response depending on the context.


So if the context used is "lineItems" then the records would be fetched using the lineItem ids passed in the request body. Likewise creative ids would be used if the context is "creatives". Irrespective of the context the request body syntax remains same for create operations.

We can also associate targetings to creatives under the context of line items.


If we need to delete all the creative associated with a line item then we must configure an empty association.

Info
For more information about UAS Line Item Management Services, refer to Line Item Management Services (UAS)

Supported Operations

Service Name: /lineitemcreativeassociations/

                                             

Method PathHTTP MethodDescriptionLink to Definition
/lineitemcreativeassociations/lineitems/ {lineItemId} /configure POSTAssociates the Creatives to the Line Item ids passed in the request body.Configure Creatives to the Line Item
/lineitemcreativeassociations/creatives/ {creativeId} /configure POSTAssociates the Creatives to the Line Item and returns data using the Creative ids passed in ht request body.Configure Line Items to Creative
/ lineitemcreativeassociations /lineitems/{ lineItemId } GETRetrieves the details of a specific association for the requested Line Item ID.Retrieve Association for a Line Item
/ lineitemcreativeassociations /creatives/{ creativeId } GETRetrieves the details of a specific association for the requested Creative ID.Retrieve Association for a Creative
/lineitemcreativeassociations/ GET

Retrieves the association between Line Items and Creatives.

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.

Find more details about how to use dimensions, sort and filter options here.

Retrieve All Associations
/lineitemcreativeassociations/?dimensions={comma separated dimensions}&filters={filters} GETRetrieves the details of the association with the dimensions and filters used.Generic Search
Info
titleImportant notes…
  • When user is trying to unlink a creative from line item and that creative has targeting set on it, system hard deletes target object corresponding to the unlinked creative.
  • Targetings can be associated to creatives only through line item context.
  • target and targetId objects are returned in response of get lineitemcreativeassociations by line item id or search lineitemcreativeassociations only when targeting is set for creatives and the targeting is not just RON for inventory.


Configure Creatives to the Line Item

Overview

This API enables you to associate the Creatives to the Line Item. We can also set targeting to creatives under the context of line item with this API.

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

                                                    

Targeting, if set to null does not create / update existing target object in the system.

In order to configure a specific targeting, for example, say geo,  pass following input :

Parameter NameTypeRequiredValidationsDescription
lineItemNumericYes

LineItem Id must be available in the system.

Any LineItem Id that is available in the lineItem table.
creativeNumericYes

Creative Id must be available in the system.

Any Creative Id that is available in the Creative table.
sequenceNumericYesSequence must be 1 to 100Sequence assigned to association
weightNumericNoWeight must be greater than 0Weight assigned to association
startDateDateNostartDate should be greater than or equal to current date.

Start date of the association.

Note: This is not yet honored by the Unified Ad Server while serving the Creatives.

endDateDateNoendDate should be greater than or equal to start date.

End Date of the association

Note: This is not yet honored by the Unified Ad Server while serving the Creatives.Note: 

targetingMapNo

Values = valid target entity.

Targeting is inputted as a map of key and target objects.

Creative Targeting supports only a subset of targetings, which include following :

  1. Geo/location
  2. Browser Language
  3. Hyper Local
  4. Hyper Local Data Source
  5. Inventory
  6. Custom Key
  7. Devices
  8. IP range
  9. Audience
  10. OS
Code Block
languagejs
linenumberstrue
"targets" : {
	....,
	"geo": {
       "targets": [
           {
               "targetValue": 118205,
               "exclude": false,
               "targetLevel": 3
           },
           {
               "targetValue": 118206,
               "exclude": false,
               "targetLevel": 3
           }
       ]
  	 },
	....
}

In order to remove all targetings, send following input

Code Block
languagejs
linenumberstrue
{
   "targeting": {}
}

In order to remove a specific targeting for example, to reset geo targeting, send following input

Code Block
languagejs
linenumberstrue
{
   "targeting" : {
		....,
		"geo": {}
		.....
	}
}
targetPhoenixTarget objectNo

This parameter is not expected in input.

This is an output parameter and is returned if targeting is set on creative while linking it to a line item.

If targeting is set to creative while linking it to a line item, target object is returned in response.targetIdIntegerNo

This parameter is not expected in input.

This is an output parameter and is returned if targeting is set on creative while linking it to a line item.

If targeting is set to creative while linking it to a line item, targetId is returned in response.

Request Sample URL    


Code Block
languagejs
linenumberstrue
https://api.pubmatic.com/v1/uas/lineitemcreativeassociations/lineitems/1/configure 


Sample Request JSON

    

Code Block
languagejs
linenumberstrue
[ 
   { 
      "creative":{ 
         "id":1
      },
      "weight":80,
      "startDate":"2016-03-27T00:00:00",
      "endDate":"2016-03-29T00:00:00",
	  "targeting": {
            "browserLanguage": {
                "targets": [
                    {
                        "targetValue": 1,
                        "exclude": false,
                        "targetLevel": 1,
                        "name": "Afrikaans"
                    },
                    { 
                       "targetValue": 2,
                        "exclude": false,
                        "targetLevel": 1,
                        "name": "Aragonese"
                    },
                     {
                        "targetValue": 3,
                        "exclude": false,
                        "targetLevel": 1,
                        "name": "Aragonese"
                    }
                ]
            },
            "customKey": {
                "targets": [
                    {
                        "targetValue": {
                            "customKey": {
                                "id": 5,
                                "name": "Height",
                                "status": {
                                    "id": 1
                                }
                            },
                            "target": {
                                "id": 2721122,
                                "isPreset": 0
                            },
                            "operator": {
                                "id": 3,
                                "name": "IS GREATER THAN"
                            },
                            "customValue": {
                                "value": "6"
                            },
                            "groupId": 1,
                            "setId": 1
                        },
                        "exclude": false,
                        "targetLevel": 1
                    }
                ]
            },
            "device": {
                "targets": [
                    {
                        "targetValue": 10690,
                        "exclude": false,
                        "targetLevel": 1,
                        "deviceTypeId": 3,
                        "deviceValue": "3Go",
                        "make": "3Go"
                    },
                    {
                        "targetValue": 10691,
                        "exclude": false,
                        "targetLevel": 1,
                        "deviceTypeId": 3,
                        "deviceValue": "3Q",
                        "make": "3Q"
                    }
                ]
            },
            "geo": {
                "targets": [
                    {
                        "targetValue": 232,
                        "exclude": false,
                        "targetLevel": 1,
                        "countryCode": "US",
                        "name": "United States"
                    },
                    {
                        "targetValue": 5,
                        "exclude": false,
                        "targetLevel": 1,
                        "countryCode": "AF",
                        "name": "Afghanistan"
                    }
                ]
            },
            "hyperLocal": {
                "targets": [
                    {
                        "targetValue": {
                            "latitude": 5.4065013,
                            "longitude": 100.2559077,
                            "radius": 3,
                            "radiusInKm": 3,
                            "radiusUnit": "km"
                        },
                        "exclude": false
                    }
                ]
            },
            "hyperLocalDataSource": {},
            "inventory": {
                "targets": [
                    {
                        "targetValue": 10040674,
                        "exclude": false,
                        "targetLevel": 2,
                        "name": "RobotBannerAdunitAllParamsUncategorized-01-30-2019 14-31-30nnykt"
                    },
                    {
                        "targetValue": 10040675,
                        "exclude": false,
                        "targetLevel": 2,
                        "name": "RobotBannerAdunitAllParamsUncategorized-01-30-2019 14-31-37stzmf"
                    }
                ]
            },
            "ipRange": {
                "targets": [
                    {
                        "targetValue": {
                            "from": "10.10.10.10",
                            "to": "11.111.111.111"
                        },
                        "exclude": false,
                        "targetLevel": 1
                    }
                ]
            },
            "os": {
                "targets": [
                    {
                        "targetValue": 141,
                        "exclude": false,
                        "targetLevel": 1,
                        "osTypeId": 23,
                        "osName": "RIM OS"
                    },
                    {
                        "targetValue": 119,
                        "exclude": false,
                        "targetLevel": 1,
                        "osTypeId": 31,
                        "osName": "Windows Mobile OS"
                    }
                ]
            },
            "zip": {}
        }
   },
   { 
      "creative":{ 
         "id":2001
      },
      "weight":500,
      "startDate":"2016-03-29T00:00:00",
      "endDate":"2016-03-29T00:00:00",
      "targeting": {
            "browserLanguage": {
                "targets": [
                    {
                        "targetValue": 1,
                        "exclude": false,
                        "targetLevel": 1,
                        "name": "Afrikaans"
                    },
                    {
                        "targetValue": 2,
                        "exclude": false,
                        "targetLevel": 1,
                        "name": "Aragonese"
                    },
                     {
                        "targetValue": 3,
                        "exclude": false,
                        "targetLevel": 1,
                        "name": "Aragonese"
                    }
                ]
            },
            "customKey": {
                "targets": [
                    {
                        "targetValue": {
                            "customKey": {
                                "id": 5,
                                "name": "Height",
                                "status": {
                                    "id": 1
                                }
                            },
                            "target": {
                                "id": 2721122,
                                "isPreset": 0
                            },
                            "operator": {
                                "id": 3,
                                "name": "IS GREATER THAN"
                            },
                            "customValue": {
                                "value": "6"
                            },
                            "groupId": 1,
                            "setId": 1
                        },
                        "exclude": false,
                        "targetLevel": 1
                    }
                ]
            },
            "device": {
                "targets": [
                    {
                        "targetValue": 10690,
                        "exclude": false,
                        "targetLevel": 1,
                        "deviceTypeId": 3,
                        "deviceValue": "3Go",
                        "make": "3Go"
                    },
                    {
                        "targetValue": 10691,
                        "exclude": false,
                        "targetLevel": 1,
                        "deviceTypeId": 3,
                        "deviceValue": "3Q",
                        "make": "3Q"
                    }
                ]
            },
            "geo": {
                "targets": [
                    {
                        "targetValue": 232,
                        "exclude": false,
                        "targetLevel": 1,
                        "countryCode": "US",
                        "name": "United States"
                    },
                    {
                        "targetValue": 5,
                        "exclude": false,
                        "targetLevel": 1,
                        "countryCode": "AF",
                        "name": "Afghanistan"
                    }
                ]
            },
            "hyperLocal": {
                "targets": [
                    {
                        "targetValue": {
                            "latitude": 5.4065013,
                            "longitude": 100.2559077,
                            "radius": 3,
                            "radiusInKm": 3,
                            "radiusUnit": "km"
                        },
                        "exclude": false
                    }
                ]
            },
            "hyperLocalDataSource": {},
            "inventory": {
                "targets": [
                    {
                        "targetValue": 10040674,
                        "exclude": false,
                        "targetLevel": 2,
                        "name": "RobotBannerAdunitAllParamsUncategorized-01-30-2019 14-31-30nnykt"
                    },
                    {
                        "targetValue": 10040675,
                        "exclude": false,
                        "targetLevel": 2,
                        "name": "RobotBannerAdunitAllParamsUncategorized-01-30-2019 14-31-37stzmf"
                    }
                ]
            },
            "ipRange": {
                "targets": [
                    {
                        "targetValue": {
                            "from": "10.10.10.10",
                            "to": "11.111.111.111"
                        },
                        "exclude": false,
                        "targetLevel": 1
                    }
                ]
            },
            "os": {
                "targets": [
                    {
                        "targetValue": 141,
                        "exclude": false,
                        "targetLevel": 1,
                        "osTypeId": 23,
                        "osName": "RIM OS"
                    },
                    {
                        "targetValue": 119,
                        "exclude": false,
                        "targetLevel": 1,
                        "osTypeId": 31,
                        "osName": "Windows Mobile OS"
                    }
                ]
            },
            "zip": {}
        }
   }
]‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Response

Sample Response JSON

 In case targetings are set at creative level, we do get target object and targetId in response.    

Code Block
languagejs
linenumberstrue
[ 
   { 
      "lineItem":{ 
         "id":1,
         "name":"Test Line Item 1",
         "url":"http://api.pubmatic.com/v1/uas/lineitems/1"
      },
      "creative":{ 
         "id":1
      },
      "weight":80,
      "startDate":"2016-03-27T00:00:00",
      "endDate":"2016-03-29T00:00:00",
      "target": {
            "id": 2721132,
            "isPreset": 0
      },
      "targetId": 2721132
   },
   { 
      "lineItem":{ 
         "id":1,
         "name":"Test Line Item 1",
         "url":"http://api.pubmatic.com/v1/uas/lineitems/1"
      },
      "creative":{ 
         "id":2001
      },
      "weight":500,
      "startDate":"2016-03-29T00:00:00",
      "endDate":"2016-03-29T00:00:00",
	  "target": {
            "id": 2721133,
            "isPreset": 0
      },
      "targetId": 2721133
 	}
]‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍


Configure Line Items to Creative

Overview

This API enables you to associate the Line Items to Creatives. Creative Targetings cannot be created in this context.

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
lineItemNumericYes

LineItem Id must be available in the system.

Any LineItem Id that is available in the lineItem table.
creativeNumericYes

Creative Id must be available in the system.

Any Creative Id that is available in the Creative table.
sequenceNumericYesSequence must be 1 to 100Sequence assigned to association
weightNumericNoWeight must be greater than 0Weight assigned to association
startDateDateNostartDate should be greater than or equal to current date.

Start date of the association

Note: This is not yet honored by the Unified Ad Server while serving the Creatives.

endDateDateNoendDate should be greater than or equal to start date.

End Date of the association

Note: This is not yet honored by the Unified Ad Server while serving the Creatives.

Request Sample URL    


Code Block
languagejs
linenumberstrue
https://api.pubmatic.com/v1/uas/lineitemcreativeassociations/creatives/3/configure 


Sample Request JSON

    

Code Block
languagejs
linenumberstrue
[ 
   { 
      "lineItem":{ 
         "id":1
      }
   },
   { 
      "lineItem":{ 
         "id":2
      }
   }
]‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Response

Sample Response JSON

    

Code Block
languagejs
linenumberstrue
[ 
   { 
      "lineItem":{ 
         "id":1,
         "name":"Test Line Item 1",
         "url":"http://api.pubmatic.com/v1/uas/lineitems/1"
      },
      "creative":{ 
         "id":3,
         "name":"Test Creative 3",
         "url":"http://api.pubmatic.com/v1/uas/creatives/3"
      }
   },
   { 
      "lineItem":{ 
         "id":2,
         "name":"Test Line Item 2",
         "url":"http://api.pubmatic.com/v1/uas/lineitems/2"
      },
      "creative":{ 
         "id":3,
         "name":"Test Creative 3",
         "url":"http://api.pubmatic.com/v1/uas/creatives/3"
      }
   }
]‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Retrieve Association for a Line Item

Overview

This API enables you to retrieve an association for a line item.

Request

           


Request Headers

                        

#e3e4e5



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.


F

Info
or more information about access tokens, refer to Getting Started with PubMatic APIs.


Request Body Parameters

                                                    

targetId

Parameter NameTypeRequiredValidationsDescription
lineItemNumericYes

LineItem Id must be available in the system.

Any LineItem Id that is available in the lineItem table.
creativeNumericYes

Creative Id must be available in the system.

Any Creative Id that is available in the Creative table.
sequenceNumericYesSequence must be 1 to 100Sequence assigned to association
weightNumericNoWeight must be greater than 0Weight assigned to association
startDateDateNostartDate should be greater than or equal to current date.

Start date of the association

Note: This is not yet honored by the Unified Ad Server while serving the Creatives.

endDateDateNoendDate should be greater than or equal to start date.

End Date of the association

Note: This is not yet honored by the Unified Ad Server while serving the Creatives.
 

IntegerNo

This parameter is not expected in input.

This is an output parameter and is returned if targeting is set on creative while linking it to a line item.

Id of the creative targeting.
targetPhoenixTarget ObjectNo

This parameter is not expected in input.

This is an output parameter and is returned if targeting is set on creative while linking it to a line item.

PhoenixTarget object used to set creative targeting.

Request Sample URL


Code Block
languagejs
linenumberstrue
https://api.pubmatic.com/v1/uas/lineitemcreativeassociations/lineitems/1


Response

Sample Response JSON

    

Code Block
languagejs
linenumberstrue
[
   {
      "creativelineItem":{
         "id":1,
         "name":"Test CreativeLine 1Item",
         "url":"http://api.pubmatic.com/v1/uas/creativeslineitems/1"
      },
        "targetcreative": {
            "id": 27211321,
            "isPresetname":"Test 0Creative 1",
       },  "url":"http://api.pubmatic.com/v1/uas/creatives/1"
      "targetId":}
2721132    },
   {
      "creativelineItem":{
         "id":21,
         "name":"Test CreativeLine 2Item",
         "url":"http://api.pubmatic.com/v1/uas/creativeslineitems/21"
       },
        "targetcreative": {
            "id": 27211332,
            "isPresetname":"Test 0Creative 2",
       },  "url":"http://api.pubmatic.com/v1/uas/creatives/2"
      "targetId": 2721133}
   }
]‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Retrieve Association for a Creative

Overview

This API enables you to retrieve an association for a Creative.

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
lineItemNumericYes

LineItem Id must be available in the system.

Any LineItem Id that is available in the lineItem table.
creativeNumericYes

Creative Id must be available in the system.

Any Creative Id that is available in the Creative table.
sequenceNumericYesSequence must be 1 to 100Sequence assigned to association
weightNumericNoWeight must be greater than 0Weight assigned to association
startDateDateNostartDate should be greater than or equal to current date.

Start date of the association

Note: This is not yet honored by the Unified Ad Server while serving the Creatives.

endDateDateNoendDate should be greater than or equal to start date.

End Date of the association

Note: This is not yet honored by the Unified Ad Server while serving the Creatives.
 

Request Sample URL

Code Block
languagejs
linenumberstrue
https://api.pubmatic.com/v1/uas/lineitemcreativeassociations/creatives/1 


Response

Sample Response JSON

    

Code Block
languagejs
linenumberstrue
[
   {
      "lineItem":{
         "id":1,
         "name":"Test Line Item",
         "url":"http://api.pubmatic.com/v1/uas/lineitems/1"
      },
      "creative":{
         "id":1,
         "name":"Test Creative 1",
         "url":"http://api.pubmatic.com/v1/uas/creatives/1"
     }
   }
]‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍


Retrieve All Associations

Overview

This API enables you to retrieve all associations between Line Items and Creatives for 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.


Refer to Common Request Query Parameters for more information about using dimensions, filters and sorting, 

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
lineItemNumericYes

LineItem Id must be available in the system.

Any LineItem Id that is available in the lineItem table.
creativeNumericYes

Creative Id must be available in the system.

Any Creative Id that is available in the Creative table.
sequenceNumericYesSequence must be 1 to 100Sequence assigned to association
weightNumericNoWeight must be greater than 0Weight assigned to association
startDateDateNostartDate should be greater than or equal to current date.

Start date of the association

Note: This is not yet honored by the Unified Ad Server while serving the Creatives.

endDateDateNoendDate should be greater than or equal to start date.

End Date of the association

Note: This is not yet honored by the Unified Ad Server while serving the Creatives.
 

targetIdIntegerNo

This parameter is not expected in input.

This is an output parameter and is returned if targeting is set on creative while linking it to a line item.

Id of the creative targeting.
targetPhoenixTarget ObjectNo

This parameter is not expected in input.

This is an output parameter and is returned if targeting is set on creative while linking it to a line item.

PhoenixTarget object used to set creative targeting.

Request Sample URL


Code Block
languagejs
linenumberstrue
https://api.pubmatic.com/v1/uas/lineitemcreativeassociations/


Response

Sample Response JSON


Code Block
languagejs
linenumberstrue
{
   "metaData":{
      "startIndex": 1,
      "totalRecords": 3,
      "pageNumber": 1,
      "endIndex": 100,
      "pageSize": 100
   },
   "items":[
      {
         "lineItem":{
            "id":1,
            "name":"Test Line Item 1",
            "url":"http://api.pubmatic.com/v1/uas/lineitems/1"
         },
         "creative":{
            "id":1,
            "name":"Test Creative 1",
            "url":"http://api.pubmatic.com/v1/uas/creatives/1"
         },
        "target": {
            "id": 2721132,
            "isPreset": 0
        },
        "targetId": 2721132
 	  },
      {
         "lineItem":{
            "id":1,
            "name":"Test Line Item 1",
            "url":"http://api.pubmatic.com/v1/uas/lineitems/1"
         },
         "creative":{
            "id":2,
            "name":"Test Creative 2",
            "url":"http://api.pubmatic.com/v1/uas/creatives/2"
         },
        "target": {
            "id": 2721133,
            "isPreset": 0
        },
        "targetId": 2721133
 	  },
      {
         "lineItem":{
            "id":2,
            "name":"Test Line Item 2",
            "url":"http://api.pubmatic.com/v1/uas/lineitems/2"
         },
         "creative":{
            "id":3,
            "name":"Test Creative 3",
            "url":"http://api.pubmatic.com/v1/uas/creatives/3"
         },
         "target": {
            "id": 2721134,
            "isPreset": 0
         },
        "targetId": 2721134
      }
   ]
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍


Generic Search

Overview

This API enables you to retrieve the associations between Line Items and Creatives for your account according to filters and dimensions used in the query. 


Refer to Common Request Query Parameters for more information about using dimensions, filters and sorting, 

Request

           

URIHTTP Method
https://api.pubmatic.com/v1/uas/lineitemcreativeassociations/?dimensions={comma separated dimensions}&filters={filter condition 1}&filter={filter condition n }&sort={any dimension mentioned in dimension list}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.

Request Body Parameters

                                                    

Parameter NameTypeRequiredValidationsDescription
lineItemNumericYes

LineItem Id must be available in the system.

Any LineItem Id that is available in the lineItem table.
creativeNumericYes

Creative Id must be available in the system.

Any Creative Id that is available in the Creative table.
sequenceNumericYesSequence must be 1 to 100Sequence assigned to association
weightNumericNoWeight must be greater than 0Weight assigned to association
startDateDateNostartDate should be greater than or equal to current date.

Start date of the association

Note: This is not yet honored by the Unified Ad Server while serving the Creatives.

endDateDateNoendDate should be greater than or equal to start date.

End Date of the association

Note: This is not yet honored by the Unified Ad Server while serving the Creatives.
 

targetPhoenixTarget ObjectNo

This parameter is not expected in input.

This is an output parameter and is returned if targeting is set on creative while linking it to a line item.

PhoenixTarget object used to set creative targeting.
targetIdIntegerNo

This parameter is not expected in input.

This is an output parameter and is returned if targeting is set on creative while linking it to a line item.

Id of target object

Generic Search Request Sample URL

https://api.pubmatic.com/v1/uas/lineitemcreativeassociations/?dimensions={comma separated dimensions}&filters={filter condition 1}&filter={filter condition n }&sort={any dimension mentioned in dimension list}

Response

Sample Response JSON


Code Block
languagejs
linenumberstrue
{
   "metaData":{
        "startIndex": 1,
        "totalRecords": 1,
        "pageNumber": 1,
        "endIndex": 1,
        "pageSize": 100
   },
   "items":[
      {
         "lineItem":{
            "id":2,
            "name":"Test Line Item 2",
            "url":"http://api.pubmatic.com/v1/uas/lineitems/2"
         },
         "creative":{
            "id":3,
            "name":"Test Creative 3",
            "url":"http://api.pubmatic.com/v1/uas/creatives/3"
         },
         "target": {
            "id": 2721132,
            "isPreset": 0
         },
        "targetId": 2721132
      }
   ]
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

     

Error Codes 

                               

Sr. NoError CodesDescription
1.

PH_MISSING_OR_INVALID_PARAMETER

This error occurs when a mandatory field is missing or its value is not valid (not present in database).

It can occur for following fields in case of Line Item Creative Association API.

  1. lineItem.id
  2. creative.id
2.PH_UNSUPPORTED_FIELD_FOR_ENTITY_TYPEThis error occurs while associating creatives to a PMP or RTB type line item.
3.PH_ENTITY_RANGE_INCLUSIVEThis error occurs when value of creative weight or sequence is not in allowed range.
4.PH_DUPLICATE_ENTRIES_FOUNDThis error occurs while associating duplicate creative ids to the same line item.
5.PH_MISMATCH_BETWEEN_ADVERTISERSThis error occurs while associating creative to a line item and vice versa in case they belong to different accounts or advertisers.
6.PH_UNSUPPORTED_FIELD_FOR_ENTITY_TYPEThis error occurs when user is trying to set creative targetings for creatives linked to lineitems of type PMP / RTB
7.PH_UNSUPPORTED_STATUSThis error occurs when user is trying to set creative targetings for creatives linked to lineitems having status archived / completed.
8.PH_TARGETING_NOT_SUPPORTEDThis error occurs if we try to set unsupported targetings to creatives in context of a line item
9.PH_CREATIVE_TARGETING_ALREADY_EXISTSThis error occurs when user tries to add targeting to a creative which already has targeting set on it under line item context
10.PH_CREATIVE_TARGETING_HAVING_NULL_TARGET_FOR_UPDATEThis error occurs when we try to update a creative targeting which has not been created earlier.