Line Item API (UAS)

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

Description

The Unified Ad Server Line Item API creates, updates and retrieves Line Items.

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

Supported Methods

Important notes:

  • The following operations are not supported for PMP type of Line Items except GET Method.
  • PMP Line Item in Unified Ad Server is a proxy presentation for deals created from PubMatic Private Marketplace.
  • To create PMP type of Line Item please refer to Product APIs (For Publishers & Demand Partners)  to create a deal.

 Service Name: /lineitems/

                                             

Method PathHTTP MethodDescriptionLink to Definition
/lineitems/POSTThis API method will create only one Line Item per request. This will be in transition.Create a Line Item
/lineitems/{id}GETRetrieve the details of a specific Line Item for the requested id.Retrieve the Details of a Line Item
/lineitems/GET

Retrieve a list of Line Items associated with your account.

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.

Retrieve a List of Line Items
/lineitems/{id}PUT

This API method updates a single line item. This will be in transaction.

This method will do a full update. If the request does not contain a value for an attribute it will either be set to NULL/default value or if it is mandatory, it will fail and no line item will be updated.

Ensure that you are passing all required attribute values.

Update a Line Item
/lineitems/{id}PATCH

This API method performs a patch of a Line Item  (e.g., to change only the status of a Line Item).

NOTE : It is different than PUT. In PUT full replacement of the Object takes place.

Update (Patch) a Line Item
/lineitems/{id}DELETE

This API method enables you to delete (archive) a Line Item

Archival of a Line Item indicates that it will not be used in Ad Serving.

Delete a Line Item
/lineitems/adunit/{adUnitId}GET

This API method is used to return the lineitems targeted against the specified adUnit.
It returns set of lineitems based on three params :

  • ron : returns the lineitems targeted against Run On Network (RON) adunits
  • direct : returns the lineitems targeted against the specified adunit.
  • inherited : retrieved the set of parent adunits and returns the lineitems targeted against the each of the parent adunit.
Getting the Line Items targeted to an adUnit

 

Create a Line Item

Overview

This API enables the creation of a 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 NameTypeRequiredValidationsDescriptions
accountIntegerYes

Account of the publisher for which this Line Item will be created.

Account of the Publisher
nameStringYes

Name can be a maximum of 255 characters consisting of letters, numbers, dashes, hyphens, periods, asterisks and colons.

Name should be unique for your account.

Line Item Name
orderIntegerYesShould be valid and non-negative identifier for order presented by the Unified Ad Server.Identifier for the Order that will be mapped to the Line Item.
ioStringNoInsertion order number; should not be more than 255 characters.Insertion order details.
startDateStringYes

Date and Time within Order start and end date and time.

Date and Time must be in  yyyy-MM-dd'T'HH:mm:ss (E.g. 2016-06-01T00:00:00)

Start date and time of an line item expected to start the delivering.

You can also pass "now" rather than passing explicit date if you would like to star the Line Item ASAP.  API sets the dates based on following conditions:

  • If Order start date is already past, Line Item start date will be current date and time with respect order Time zone.
  • If Order start date is futuristic, Line Item start date will same as Order start date and time with respect order Time zone.

e.g. :

    
{
        "startDate" : "now"
}
endDateStringNo

End date and time the line item expected to complete.

End date and time should be greater than start date and time.

End date should be less than or equal to order end date and time.

Date and Time must be in  yyyy-MM-dd'T'HH:mm:ss 
E.g. 2016-06-01T00:00:00

If you would like to set a line item, which will run for indefinitely, please do not pass this parameter.

Line Item end date and time.
lineItemTypeIntegerNo

Should be valid and exist in the system.

If you do not pass the lineItem type system will "Standard" as a type.

Type of Line Item. You can retrieve the line item types using Line Item Type API.

Based on line item type, you have to select valid goalType, goalPricing and goalUnit. The following table summarizes the rules.

                                                    
Line Item TypeGoal PricingGoal TypeGoal Unit Description
SponsorshipCPM/CPCImpressionsPercentage% of total impressions (0 to 100%)
StandardCPMImpressionsAbsoluteNumber of impressions
 CPCClicksAbsoluteNumber of clicks
HouseCPM/CPCImpressionsPercentage% of remaining impression
PMPCPMImpressionsPercentage% of remaining impressions
RTBCPMImpressionsPercentage% of remaining impressions

Note: For PMP and RTB type of line item, default priority 6 is set but could have a priority range between 5-16.

priorityIntegerNoPriority for the line item. The priority assigned depends on the type of line item. See table to the right.

Specifies the priority of a line item, relative to competing line items, in cases when inventory is over committed.

                       
Line Item TypePriority Range
Sponsorship1-4
Standard5-8
House13-16
Open Exchange5-16
statusIntegerYes

Status should be valid and exist in the system. 

The default is "Draft" for a newly created line item if it does not have a creative. Otherwise the default line item status will be "Active." 

Status of the Line Item.

You can retrieve the list of statuses using the Status API.

The following statuses are supported for Line Item:

                                         
IdName
1Active
2Inactive
4Archived
Draft
Delivering
8Paused
9Completed
11 In Review
12 Rejected

System Make the Line Item to Active once user mapped the creatives to that line item. This is only valid for guaranteed line item like Standards, Sponsorship and House.

For Programatic line items like ( Open Exchange, PMP ), the status of line item set to Active once created as user can not map the creative to this.

Status "In Review" and "Rejected" is very specific and applicable to PMP type of line item and user can set it through API. However you can use "In Review" and "Rejected" to apply filters and for searching Line item having this status.

targetIntegerNoIt should be valid and non negative.

The selected targeting criteria is set against the target id. You have to use this identifier to set the various targeting for the given line item. Please refer to Line Item Targeting Services API.

goalPricingIntegerYesIt should be valid and non negative.

Describes how the line item is priced.

To retrieve the list of supported pricing models by the Unified Ad Server, use the Goal Pricing API.

               
Pricing ModelDescription
1CPM: Cost per thousand impressions
2CPC: Cost per click
goalIntegerYesShould be valid and non negative; should be greater than zero.

Goal defines the total aim (either impressions or clicks) of the campaign. For guaranteed line items like sponsorship or standard, the ad server will try to achieve the goal (based on available inventory). For programmatic line items ( Open Exchange and PMP ), a goal is not required.

Example: A CPC pricing model's chosen goal is a whole number, indicating number of clicks. If Sponsorship is chosen then goal is a whole number indicating percentage of inventory (1 - 100).

goalTypeIntegerYesShould be valid and exist in the system.

Goals set for line item either in impressions or clicks.

To retrieve the list of Goal Types supported by the Unified Ad Server, use the Goal Type API.

               
Goal TypeDescription
1Impressions
2Clicks
goalUnitIntegerYesShould be valid and exist in the system.

Goal Unit. This can be either an Absolute Number or in the form of a Percentage for the goal.

To retrieve the list of Goal Units supported by the Unified Ad Server, used the Goal Unit API.

paceIntegerNo 

For the Guaranteed Line Items, this determines how the ad server paces impressions for the Line Items, which can be one of the following:

                       
Pace IdNameDescription
1EvenThe ad server evenly distributes the delivery of impressions over the time period. This is the default.
2ASAPThe ad server delivers impressions as quickly as possible until either the end date or the volume goal is met.
3Front LoadedFront loading defines how much to over pace line items at the beginning of flight.

Note: If a pacing value for a standard type of line item, the default value will be set to "Even."

frontLoadPercentIntegerNo

Should be in the range of 1-40%

It should be applicable only for pace of type 3, which is Front Loaded. For other types, frontLoadPercent is NULL.

Front loading defines how much to over pace line items at the beginning of their flight. For a given type of 3, you can assign a maximum load of 40%.
frequencyCapStringNoShould be valid and non negative.Frequency Cap defines how many times a specific end user sees an advertising message during a specific time period. A Line Item level frequency cap applies to all Creatives belonging to that Line Item.
schedulesArray of Line Item Schedule ObjectsNoOptional
  1. Create Line Item without Scheduling
    Pass null value
  2. To remove all creatives information pass [ ] (empty array)
  3. How can I schedule a line item to run on all days of week with single time slot?
    To run a Line Item for all days of the week, but at a specific time pass day of the week id = null
    e.g.,      

    { "dayOfWeek" : { "id" : null },  "timeStart" : "04:5:00", 
    "timeEnd" : "15:04:00", "timeZoneType" : "P"  }
  4. How can I schedule a Line Item to run on all days of the week with multiple time slots?     

    { "dayOfWeek" : { "id" : null }, "timeStart" : "03:00:00", "timeEnd" :
     "06:00:00", 
    "timeZoneType" : "P" },

    { "dayOfWeek" : { "id" : null }, "timeStart" : "6:15:10", "timeEnd" : 
    "07:05:50", "timeZoneType" : "P" }
  5. timeZoneType : Though API expecting separate values for time zone type. Client must send same value across all schedules
    Following is wrong (Though API is not validating it)
    Invalid Input: Timezone type must be same for all entries    
    { "dayOfWeek" : { "id" : 1 }, "timeStart" : "03:00:00", "timeEnd" : 
    "06:00:00", "timeZoneType" : "P" },
    { "dayOfWeek" : { "id" : 2 }, "timeStart" : "04:00:00", "timeEnd" : 
    "05:00:00", "timeZoneType" : "U" },
    { "dayOfWeek" : { "id" : 3 }, "timeZoneType" : "P" },

    Valid Input (updated 2nd record)     
    { "dayOfWeek" : { "id" : 1 }, "timeStart" : "03:00:00", "timeEnd" : 
    "06:00:00", "timeZoneType" : "P" },
    { "dayOfWeek" : { "id" : 2 }, "timeStart" : "04:00:00", "timeEnd" : 
    "05:00:00", "timeZoneType" : "P" },
    { "dayOfWeek" : { "id" : 3 }, "timeZoneType" : "P" },
  6. Valid values for timezonetype                    
    timeZoneType ValueDescription
    PPublisher Time Zone
    UUser Time Zone
    null (Not recommended)Publisher Time Zone


     
rateDouble -up to 2 decimal placesYesMust be greater than or equal to 0 and less than or equal to 999999999.00Represents the average rate (ecpm) of the selected line item.
creativeRotationIntegerNo

Should be valid and exist in the system.

Default is "Evenly" for newly created line items is not provided.

Creative Rotation to be applied for the creatives linked to the Line Item. You cannot change the Creative Rotation if the Line Item is in delivering mode. You need to either Pause or Deactivate it to change the Creative Rotation.

You can retrieve the list of creative rotation types using Creative Rotation API.

                       
IdName
1Evenly
2Sequential
3Weighted
4Optimized
creativesArray of LineItem Creative ObjectsNoOptional
  1. Create Line Item without creatives
    Pass null value.
  2. You must have at least one creative associated with a Line Item at any point in time, if the state is not in Draft.
  3. If createiveRotation provided is Evenly or Optimized then you can pass only creative with null values for sequence and weight.     
    {"creative": {"id": 14,"name": "Novartis 250x250",
    "url":"},"sequence":2}
  4. If creativeRotation provided is Sequential then you should pass creative along with sequence value. Weight can be null. No two sequence can be of same value except for sequence value 100.
          
    [{"creative": {"id": 14,"name": "Novartis 250x250","url":"},
    "sequence":2},
     {"creative": {"id": 15,"name": "AMD 300x600-Test","url":"},
  5. If creativeRotation provided is Weighted then you should pass creative along with weight value. Sequence can be null.     
    [{"creative": {"id": 14,"name": "Novartis 250x250","url":"},"weight":20},
labelsList of Label ObjectsNoIf passed, labels should be valid and exist in the system.

Labels applied to the Line Item.

You can create/edit/retrieve a list of Label details using the Label Exclusion API.

You can use the field "excluded" along with "id" if you want to remove the inherited label from Advertiser or Order. e.g., "excluded": 1.

Note: If you want to remove associated labels, you must pass an empty array, i.e., [  ]. Only inherited labels (if any) will be associated.

currencyCurrency ObjectNo

Read Only

Not expected in the request

Provides the information about unit in which rate value should be treated.

While creating the line item (POST method) API internally determines the Account / Network level currency  and sets the same currency for the line item.

For PMP Type of Line Item the currency will be always Dollar ( $) irrespective of your account level currency. 

Note: This is read-only attribute.

If send in the request it will be ignored

If value is different in case of PUT/PATCH request, API returns error indicated read-only attribute

isTestBooleanNo

Default is false

You can enable the Test Flag for a Guaranteed Line Item only during create and update process. You cannot enable the Test Flag for a Lint Item that is completed or archived.

Status Transition Matrix

                                                                                           

FromToWho does it?Condition
DraftActiveSystemAs soon as Line Item has at least one Creative.
DraftArchivedUser 
ActiveDeliveringSystemAs soon as the Line Item starts Delivering.
ActiveInactiveUser 
ActivePausedUser 
DeliveringPausedUser 
DeliveringInactiveUser 
PausedActiveUser 
PausedInactiveUser 
PausedArchivedUser 
InactiveActiveUser 
InactiveArchivedUser 
CompletedArchivedUser 
ArchivedNot allowedUserNote: It is no longer permitted to change "Archived" to "Inactive."

 

Status and Editable Fields Matrix

                                                                                                                                                   

StatusIOOrderStart TimePriorityLine Item TypePricing ModelGoalPacingFrequency CapsFront Load PercentGoal TypeGoal UnitRateCreative RotationComments
DraftYESYESYESYESYESYESYESYESYESYESYESYESYESYES
  • Line Item contains no Creative
  • Status cannot be changed to Draft from the UI
ActiveYESNONOYESYESYESYESYESYESYESYESYESYESYES
  • Current Time <Start Time
  • Line Item contains at least one Creative
  • Status cannot be changed to Active from UI if Line Item is Draft.
DeliveringNONONOYESNONOYESNOYESNONONONONO
  • Start Time <==Current Time <==End Time
  • Line Item contains at least one Createive
  • Status cannot be changed to Delivering from the UI
PausedNONONOYESNONOYESNOYESNONONONOYES
  • Start Time <== Current Time <== End Time.
  • Line Item contains at least one Creative
  • Status cannot be changed to Delivering from UI.
InactiveNONO

YES

  • ONLY if Current Time is less than old Start Time
  • New Start Time cannot be before the Current Time
NONONONONONONONONONOYES
  • Active, Delivering Line Items can be manually Paused.
  • Paused Line Items need to be manually started.
CompletedNONONONONONONONONONONONONONO
  • Current Time > End Time
  • Status cannot be changed to Completed from the UI
ArchivedNONONONONONONONONONONONONONO
  • Draft, Inactive and Completed Line Items can be manually Archived
  • Archived Line Items need to be manually Deactivated.

Sample Request URL

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

Sample Request JSON

    

{
    "account": {
        "id": 118385
    },
    "name": "Test-Line-Item",
    "description": "Test LineItem",
    "schedules": [{
        "timeZoneType": "U",
        "dayOfWeek": {
            "name": "T_ALL_DAYS",
            "id": null
        },
        "timeStart": "01:00:00",
        "timeEnd": "04:00:59"
    }],
    "startDate": "2016-01-20T00:00:00",
    "endDate": "2016-01-20T00:00:00",
    "status": {
        "id": 5
    },
    "order": {
        "id": 6,
        "advertiser": {
            "id": 3
        }
    },
    "lineItemType": {
        "id": 2
    },
    "priority": 6,
    "goal": 1230,
    "rate": "12",
    "pace": {
        "id": 1
    },
    "frequencyCaps": [{
        "frequencyCapPeriod": {
            "id": 1
        },
        "periodValue": 1,
        "capValue": 123
    }],
    "labels": [{
        "id": 2,
        "isInherited": false
    }],
    "goalPricing": {
        "id": 1
    },
    "goalUnit": {
        "id": 1
    },
    "goalType": {
        "id": 1
    },
    "io": "12",
    "creativeRotation": {
        "id": 1
    },
    "creatives": []
}

Response

Sample Response JSON

    

{
    "id": 1538,
    "account": {
        "id": 118385,
        "name": "PubMatic Inc.",
        "url": "http://api.pubmatic.com/v1/uas/"
    },
    "name": "Test-Line-Item",
    "description": "Test LineItem",
    "order": {
        "id": 6,
        "name": "HOTestOrder",
        "url": "http://api.pubmatic.com/v1/uas/"
    },
    "io": "12",
    "startDate": "2016-01-20T00:00:00",
    "endDate": "2016-01-20T00:00:00",
    "lineItemType": {
        "id": 2,
        "name": "Standard",
        "url": "http://api.pubmatic.com/v1/uas/lineitemtypes/2"
    },
    "priority": 6,
    "status": {
        "id": 5,
        "name": "Draft",
        "url": "http://api.pubmatic.com/v1/uas/status/5"
    },
    "target": {
        "id": 1556,
        "isPreset": 0,
        "url": "http://$URI_PREFIX/{apiVersion}/phoenix"
    },
    "pace": {
        "id": 1,
        "name": "Even",
        "url": "http://api.pubmatic.com/v1/uas/lineitempaces/1"
    },
    "user": {
        "id": 18280,
        "url": "http://api.pubmatic.com/v1/uas/users/18280"
    },
    "goalType": {
        "id": 1,
        "name": "Impressions",
        "url": "http://api.pubmatic.com/v1/uas/goaltypes/1"
    },
    "goalUnit": {
        "id": 1,
        "name": "Absolute",
        "url": "http://api.pubmatic.com/v1/uas/goalunits/1"
    },
    "goalPricing": {
        "id": 1,
        "name": "CPM",
        "url": "http://$URI_PREFIX/{apiVersion}/phoenix/goalpricing/1"
    },
    "goal": 1230.0000000000,
    "labels": [{
        "id": 2,
        "name": "Label-2",
        "account": {
            "id": 118385,
            "url": "http://api.pubmatic.com/v1/uas/"
        },
        "labelType": {
            "id": 1,
            "name": "Ad Exclusion",
            "url": "http://api.pubmatic.com/v1/uas/labeltype/1"
        },
        "isInherited": false
    }],
    "schedules": [{
        "timeStart": "01:00:00",
        "timeEnd": "04:00:59",
        "timeZoneType": "U"
    }],
    "rate": 12.0000000000,
    "frequencyCaps": [{
        "frequencyCapPeriod": {
            "id": 1,
            "url":"http://api.pubmatic.com/v1/uas/frequencycapperiods/1"
        },
        "capValue": 123,
        "periodValue": 1
    }],
    "creativeRotation": {
        "id": 1,
        "name": "Evenly",
        "url": "http://api.pubmatic.com/v1/uas/creativerotations/1"
    },
    "updatedAt": "2016-01-20T01:03:29",
    "createdAt": "2016-01-20T01:03:29",
    "timeZone": {
        "id": 1,
        "url": "http://api.pubmatic.com/v1/uas/timezones/1"
    }
}
 

 

Retrieve the Details of a Line Item

Overview

This API enables you to retrieve the details of a 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.

Sample Request URL

https://api.pubmatic.com/v1/uas/lineitems/1538

 

Response

Sample Response JSON

    

{
    "id": 1538,
    "account": {
        "id": 118385,
        "name": "PubMatic Inc.",
        "url": "http://api.pubmatic.com/v1/uas/"
    },
    "name": "Test-Line-Item",
    "description": "Test LineItem",
    "order": {
        "id": 6,
        "name": "HOTestOrder",
        "url": "http://api.pubmatic.com/v1/uas/"
    },
    "io": "12",
    "startDate": "2016-01-20T00:00:00",
    "endDate": "2016-01-20T00:00:00",
    "lineItemType": {
        "id": 2,
        "name": "Standard",
        "url": "http://api.pubmatic.com/v1/uas/lineitemtypes/2"
    },
    "priority": 6,
    "status": {
        "id": 5,
        "name": "Draft",
        "url": "http://api.pubmatic.com/v1/uas/status/5"
    },
    "target": {
        "id": 1556,
        "isPreset": 0,
        "url": "http://api.pubmatic.com/v1/uas/phoenix"
    },
    "pace": {
        "id": 1,
        "name": "Even",
        "url": "http://api.pubmatic.com/v1/uas/lineitempaces/1"
    },
    "user": {
        "id": 18280,
        "url": "http://$URI_PREFIX/{apiVersion}/phoenix/users/18280"
    },
    "goalType": {
        "id": 1,
        "name": "Impressions",
        "url": "http://api.pubmatic.com/v1/uas/goaltypes/1"
    },
    "goalUnit": {
        "id": 1,
        "name": "Absolute",
        "url": "http://api.pubmatic.com/v1/uas/goalunits/1"
    },
    "goalPricing": {
        "id": 1,
        "name": "CPM",
        "url": "http://api.pubmatic.com/v1/uas/goalpricing/1"
    },
    "goal": 1230.0000000000,
    "labels": [{
        "id": 2,
        "name": "Label-2",
        "account": {
            "id": 118385,
            "url": "http://api.pubmatic.com/v1/uas/phoenix"
        },
        "labelType": {
            "id": 1,
            "name": "Ad Exclusion",
            "url": "http://api.pubmatic.com/v1/uas/labeltype/1"
        },
        "isInherited": false
    }],
    "schedules": [{
        "timeStart": "01:00:00",
        "timeEnd": "04:00:59",
        "timeZoneType": "U"
    }],
    "rate": 12.0000000000,
    "frequencyCaps": [{
        "frequencyCapPeriod": {
            "id": 1,
            "url":"http://api.pubmatic.com/v1/uas/frequencycapperiods/1"
        },
        "capValue": 123,
        "periodValue": 1
    }],
    "creativeRotation": {
        "id": 1,
        "name": "Evenly",
        "url": "http://api.pubmatic.com/v1/uas/creativerotations/1"
    },
    "updatedAt": "2016-01-20T01:03:29",
    "createdAt": "2016-01-20T01:03:29",
    "timeZone": {
        "id": 1,
        "url": "http://api.pubmatic.com/v1/uas/timezones/1"
    },
    "currency":
    {
        "id": 2,
        "code": "EUR",
        "sign": "€"
    }
}

 

 

Retrieve a List of Line Items

 

Overview

This API enables you to retrieve a list of a Line Item Types. 

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
nameStringYes

Name can be a maximum of 64 characters.

Name should be unique for your account.

Name of Line Item Type
descriptionStringNo

Description can be a maximum of 1024 characters.

Line Item Type description (if any)

Request Sample URL

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

Response

Sample Response

    

This will return a list of supported Line Item Types.

Update a Line Item

 

Overview

This API enables you to update a 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 NameTypeRequiredValidationsDescriptions
accountIntegerYes

Account of the publisher for which this Line Item will be created.

Account of the Publisher
nameStringYes

Name can be a maximum of 255 characters consisting of letters, numbers, dashes, hyphens, periods, asterisks and colons.

Name should be unique for your account.

Line Item Name
orderIntegerYesShould be valid and non-negative identifier for order presented by the Unified Ad Server.Identifier for the Order that will be mapped to the Line Item.
ioStringNoInsertion order number; should not be more than 255 characters.Insertion order details.
startDateStringYes

Date and Time within Order start and end date and time.

Date and Time must be in  yyyy-MM-dd'T'HH:mm:ss (E.g. 2016-06-01T00:00:00)

Start date and time of an line item expected to start the delivering.

You can also pass "now" rather than passing explicit date if you would like to star the Line Item ASAP.  API sets the dates based on following conditions:

  • If Order start date is already past, Line Item start date will be current date and time with respect order Time zone.
  • If Order start date is futuristic, Line Item start date will same as Order start date and time with respect order Time zone.

e.g. :

    

{

        "startDate":"now"

}

endDateStringNo

End date and time the line item expected to complete.

End date and time should be greater than start date and time.

End date should be less than or equal to order end date and time.

Date and Time must be in  yyyy-MM-dd'T'HH:mm:ss 
E.g. 2016-06-01T00:00:00

If you would like to set a line item, which will run for indefinitely, please do not pass this parameter.

Line Item end date and time.
lineItemTypeIntegerNo

Should be valid and exist in the system.

If you do not pass the lineItem type system will "Standard" as a type.

Type of Line Item. You can retrieve the line item types using Line Item Type API.

Based on line item type, you have to select valid goalType, goalPricing and goalUnit. The following table summarizes the rules.

                                                    
Line Item TypeGoal PricingGoal TypeGoal Unit Description
SponsorshipCPM/CPCImpressionsPercentage% of total impressions (0 to 100%)
StandardCPMImpressionsAbsoluteNumber of impressions
 CPCClicksAbsoluteNumber of clicks
HouseCPM/CPCImpressionsPercentage% of remaining impression
PMPCPMImpressionsPercentage% of remaining impressions
RTBCPMImpressionsPercentage% of remaining impressions

Note: For PMP and RTB type of line item, default priority 6 is set but could have a priority range between 5-16.

priorityIntegerNoPriority for the line item. The priority assigned depends on the type of line item. See table to the right.

Specifies the priority of a line item, relative to competing line items, in cases when inventory is over committed.

                   
Line Item TypePriority Range
Sponsorship1-4
Standard5-8
House13-16
statusIntegerYes

Status should be valid and exist in the system. 

The default is "Draft" for a newly created line item if it does not have a creative. Otherwise the default line item status will be "Active." 

Status of the Line Item.

You can retrieve the list of statuses using the Status API.

The following statuses are supported for Line Item:

                                         
IdName
1Active
2Inactive
4Archived
Draft
Delivering
8Paused
9Completed
11In Review
12Rejected

System Make the Line Item to Active once user mapped the creatives to that line item. This is only valid for guaranteed line item like Standards, Sponsorship and House.

For Programatic line items like ( Open Exchange, PMP ), the status of line item set to Active once created as user can not map the creative to this.

Status "In Review" and "Rejected" is very specific and applicable to PMP type of line item and user can set it through API. However you can use "In Review" and "Rejected" to apply filters and for searching Line item having this status.

targetIntegerNoIt should be valid and non negative.

Target is applied to Line Items. It defines where and who a Line Item is qualified to show.

Where: Publisher's inventory (site) is defined as Ad Unit(s). 

goalPricingIntegerYesIt should be valid and non negative.

Describes how the line item is priced.

To retrieve the list of supported pricing models by the Unified Ad Server, use the Goal Pricing API.

               
Pricing ModelDescription
1CPM: Cost per thousand impressions
2CPC: Cost per click
goalIntegerYesShould be valid and non negative; should be greater than zero.

Goal defines the total aim (either impressions or clicks) of the campaign. For guaranteed line items like sponsorship or standard, the ad server will try to achieve the goal (based on available inventory). For programmatic line items ( Open Exchange and PMP ), a goal is not required.

Example: A CPC pricing model's chosen goal is a whole number, indicating number of clicks. If Sponsorship is chosen then goal is a whole number indicating percentage of inventory (1 - 100).

goalTypeIntegerYesShould be valid and exist in the system.

Goals set for line item either in impressions or clicks.

To retrieve the list of Goal Types supported by the Unified Ad Server, use the Goal Type API.

               
Goal TypeDescription
1Impressions
2Clicks
goalUnitIntegerYesShould be valid and exist in the system.

Goal Unit. This can be either an Absolute Number or in the form of a Percentage for the goal.

To retrieve the list of Goal Units supported by the Unified Ad Server, used the Goal Unit API.

paceIntegerNo 

For the Guaranteed Line Items, this determines how the ad server paces impressions for the Line Items, which can be one of the following:

                       
Pace IdNameDescription
1EvenThe ad server evenly distributes the delivery of impressions over the time period. This is the default.
2ASAPThe ad server delivers impressions as quickly as possible until either the end date or the volume goal is met.
3Front LoadedFront loading defines how much to over pace line items at the beginning of flight.

Note: If a pacing value for a standard type of line item, the default value will be set to "Even."

frontLoadPercentIntegerNo

Should be in the range of 1-40%

It should be applicable only for pace of type 3, which is Front Loaded. For other types, frontLoadPercent is NULL.

Front loading defines how much to over pace line items at the beginning of their flight. For a given type of 3, you can assign a maximum load of 40%.
frequencyCapStringNoShould be valid and non negative.Frequency Cap defines how many times a specific end user sees an advertising message during a specific time period. A Line Item level frequency cap applies to all Creatives belonging to that Line Item.
schedulesArray of Line Item Schedule ObjectsNoOptional
  1. Create Line Item without Scheduling
    Pass null value
  2. To remove all creatives information pass [ ] (empty array)
  3. How can I schedule a line item to run on all days of week with single time slot?
    To run a Line Item for all days of the week, but at a specific time pass day of the week id = null
    e.g.,      

    { "dayOfWeek" : { "id" : null },  "timeStart" : "04:5:00", "timeEnd" : "15:04:00", "timeZoneType" : "P"  }
  4. How can I schedule a Line Item to run on all days of the week with multiple time slots?     

    { "dayOfWeek" : { "id" : null }, "timeStart" : "03:00:00", "timeEnd" : "06:00:00", "timeZoneType" : "P" },

    { "dayOfWeek" : { "id" : null }, "timeStart" : "6:15:10", "timeEnd" : "07:05:50", "timeZoneType" : "P" }
  5. timeZoneType : Though API expecting separate values for time zone type. Client must send same value across all schedules
    Following is wrong (Though API is not validating it)
    Invalid Input: Timezone type must be same for all entries    
    { "dayOfWeek" : { "id" : 1 }, "timeStart" : "03:00:00", "timeEnd" : "06:00:00", "timeZoneType" : "P" },
    { "dayOfWeek" : { "id" : 2 }, "timeStart" : "04:00:00", "timeEnd" : "05:00:00", "timeZoneType" : "U" },
    { "dayOfWeek" : { "id" : 3 }, "timeZoneType" : "P" },

    Valid Input (updated 2nd record)     
    { "dayOfWeek" : { "id" : 1 }, "timeStart" : "03:00:00", "timeEnd" : "06:00:00", "timeZoneType" : "P" },
    { "dayOfWeek" : { "id" : 2 }, "timeStart" : "04:00:00", "timeEnd" : "05:00:00", "timeZoneType" : "P" },
    { "dayOfWeek" : { "id" : 3 }, "timeZoneType" : "P" },
  6. Valid values for timezonetype                    
    timeZoneType ValueDescription
    PPublisher Time Zone
    UUser Time Zone
    null (Not recommended)Publisher Time Zone


     
rateDouble -up to 2 decimal placesYesMust be greater than or equal to 0 and less than or equal to 999999999.00Represents the average rate (ecpm) of the selected line item.
creativeRotationIntegerNo

Should be valid and exist in the system.

Default is "Evenly" for newly created line items is not provided.

Creative Rotation to be applied for the creatives linked to the Line Item.

You can retrieve the list of creative rotation types using Creative Rotation API.

                       
IdName
1Evenly
2Sequential
3Weighted
4Optimized
creativesArray of LineItem Creative ObjectsNoOptional
  1. Create Line Item without creatives
    Pass null value.
  2. To remove all creatives information pass [ ] (empty array)
  3. If createiveRotation provided is Evenly or Optimized then you can pass only creative with null values for sequence and weight.     

    {"creative": {"id": 14,"name": "Novartis 250x250","url":"},"sequence":2}
  4. If creativeRotation provided is Sequential then you should pass creative along with sequence value. Weight can be null. No two sequence can be of same value except for sequence value 100.
          
  5. If creativeRotation provided is Weighted then you should pass creative along with weight value. Sequence can be null.     
    [{"creative": {"id": 14,"name": "Novartis 250x250","url":"},"weight":20},
labelsList of Label ObjectsNoIf passed, labels should be valid and exist in the system.

Labels applied to the Line Item.

You can create/edit/retrieve a list of Label details using the Label Exclusion API.

You can use the field "excluded" along with "id" if you want to remove the inherited label from Advertiser or Order. e.g., "excluded": 1.

Note: If you want to remove associated labels, you must pass an empty array, i.e., [  ]. Only inherited labels (if any) will be associated.

currencyCurrency ObjectNo

Read Only

Not expected in the request

Provides the information about unit in which rate value should be treated.

While creating the line item (POST method) API internally determines the Account / Network level currency  and sets the same currency for the line item.

For PMP Type of Line Item the currency will be always Dollar ( $) irrespective of your account level currency. 

Note: This is read-only attribute.

If send in the request it will be ignored

If value is different in case of PUT/PATCH request, API returns error indicated read-only attribute

isTestBooleanNo

Default is False

You can enable the Test Flag for a Guaranteed Line Item only during create and update process. You cannot enable the Test Flag for a Lint Item that is completed or archived.

Status Transition Matrix

                                                                                           

FromToWho does it?Condition
DraftActiveSystemAs soon as Line Item has at least one Creative.
DraftArchivedUser 
ActiveDeliveringSystemAs soon as the Line Item starts Delivering.
ActiveInactiveUser 
ActivePausedUser 
DeliveringPausedUser 
DeliveringInactiveUser 
PausedActiveUser 
PausedInactiveUser 
PausedArchivedUser 
InactiveActiveUser 
InactiveArchivedUser 
CompletedArchivedUser 
ArchivedNot allowedUserNote: It is no longer permitted to change "Archived" to "Inactive."

 

Status and Editable Fields Matrix

                                                                                                                                                   

StatusIOOrderStart TimePriorityLine Item TypePricing ModelGoalPacingFrequency CapsFront Load PercentGoal TypeGoal UnitRateCreative RotationComments
DraftYESYESYESYESYESYESYESYESYESYESYESYESYESYES
  • Line Item contains no Creative
  • Status cannot be changed to Draft from the UI
ActiveYESNONOYESYESYESYESYESYESYESYESYESYESYES
  • Current Time <Start Time
  • Line Item contains at least one Creative
  • Status cannot be changed to Active from UI if Line Item is Draft.
DeliveringNONONOYESNONOYESNOYESNONONONONO
  • Start Time <==Current Time <==End Time
  • Line Item contains at least one Createive
  • Status cannot be changed to Delivering from the UI
PausedNONONOYESNONOYESNOYESNONONONOYES
  • Start Time <== Current Time <== End Time.
  • Line Item contains at least one Creative
  • Status cannot be changed to Delivering from UI.
InactiveNONO

YES

  • ONLY if Current Time is less than old Start Time
  • New Start Time cannot be before the Current Time
NONONONONONONONONONOYES
  • Active, Delivering Line Items can be manually Paused.
  • Paused Line Items need to be manually started.
CompletedNONONONONONONONONONONONONONO
  • Current Time > End Time
  • Status cannot be changed to Completed from the UI
ArchivedNONONONONONONONONONONONONONO
  • Draft, Inactive and Completed Line Items can be manually Archived
  • Archived Line Items need to be manually Deactivated.

Sample Request URL

https://api.pubmatic.com/v1/uas/lineitems/1538 

Sample Request JSON

    

{
    "name": "Test-Line-Item",
    "description": "Test LineItem",
    "schedules": [{
        "timeZoneType": "U",
        "dayOfWeek": {
            "name": "T_ALL_DAYS",
            "id": null
        },
        "timeStart": "01:00:00",
        "timeEnd": "04:00:59"
    }],
    "startDate": "2016-01-20T00:00:00",
    "endDate": "2016-01-20T00:00:00",
    "status": {
        "id": 5
    },
    "account": {
        "id": 118385
    },
    "order": {
        "id": 6,
        "advertiser": {
            "id": 3
        }
    },
    "lineItemType": {
        "id": 2
    },
    "priority": 6,
    "goal": 1200,
    "rate": "12",
    "pace": {
        "id": 1
    },
    "frequencyCaps": [{
        "frequencyCapPeriod": {
            "id": 1
        },
        "periodValue": 1,
        "capValue": 123
    }],
    "labels": [{
        "id": 2,
        "isInherited": false
    }],
    "goalPricing": {
        "id": 1
    },
    "goalUnit": {
        "id": 1
    },
    "goalType": {
        "id": 1
    },
    "io": "12",
    "creativeRotation": {
        "id": 1
    },
    "creatives": []
}

Response

Sample Response JSON

    

{
    "id": 1538,
    "account": {
        "id": 118385,
        "name": "PubMatic Inc.",
        "url": "http://$URI_PREFIX/{apiVersion}/phoenix"
    },
    "name": "Test-Line-Item",
    "description": "Test LineItem",
    "order": {
        "id": 6,
        "name": "HOTestOrder",
        "url": "api.pubmatic.com/v1/uas/"
    },
    "io": "12",
    "startDate": "2016-01-20T00:00:00",
    "endDate": "2016-01-20T00:00:00",
    "lineItemType": {
        "id": 2,
        "name": "Standard",
        "url": "http://api.pubmatic.com/v1/uas/lineitemtypes/2"
    },
    "priority": 6,
    "status": {
        "id": 5,
        "name": "Draft",
        "url": "