Line Item Creative Association (UAS)

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

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.

 

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

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}/configurePOSTAssociates the Creatives to the Line Item ids passed in the request body.Configure Creatives to the Line Item
/lineitemcreativeassociations/creatives/{creativeId}/configurePOSTAssociates 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

 

Configure Creatives to the Line Item

 

Overview

This API enables you to associate the Creatives to the Line Item.

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

Request Sample URL    

https://api.pubmatic.com/v1/uas/lineitemcreativeassociations/lineitems/1/configure 

 

Sample Request JSON

    

[ 
   {
      "creative":{
         "id":1
      },
      "weight":80,
      "startDate":"2016-03-27T00:00:00",
      "endDate":"2016-03-29T00:00:00"
   },
   {
      "creative":{
         "id":2001
      },
      "weight":500,
      "startDate":"2016-03-29T00:00:00",
      "endDate":"2016-03-29T00:00:00"
   }
]

Response

Sample Response JSON

    

[ 
   {
      "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"
   },
   {
      "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"
   }
]

 

Configure Line Items to Creative

 

Overview

This API enables you to associate the Line Items to Creatives.

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    

https://api.pubmatic.com/v1/uas/lineitemcreativeassociations/creatives/3/configure 

 

Sample Request JSON

    

[ 
   {
      "lineItem":{
         "id":1
      }
   },
   {
      "lineItem":{
         "id":2
      }
   }
]

Response

Sample Response JSON

    

[ 
   {
      "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.

 

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

https://api.pubmatic.com/v1/uas/lineitemcreativeassociations/lineitems/1

Response

Sample Response JSON

    

[
   {
      "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"
      }
   },
   {
      "lineItem":{
         "id":1,
         "name":"Test Line Item",
         "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"
       }
   }
]

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

https://api.pubmatic.com/v1/uas/lineitemcreativeassociations/creatives/1 

 

Response

Sample Response JSON

    

[
   {
      "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.

 

Request Sample URL

https://api.pubmatic.com/v1/uas/lineitemcreativeassociations/

Response

Sample Response JSON

 

{
   "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"
         }
      },
      {
         "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"
         }
      },
      {
         "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"
         }
      }
   ]
}

 

Response Codes

HTTP Status Codes

Error Codes for Line Item Creative Association

 

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.

 

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

 

{
   "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"
         }
      }
   ]
}

    

 

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.

 

 

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 21

Attachments

    Outcomes