Page tree


Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Anchor
top
top
Table of Contents
indent20px
stylenone


The Unified Ad Server Line (UAS) Item API creates, updates, and retrieves line items. The field createdBy, and many more described below, is available in the response.

Info
Before using PubMatic APIs, first generate the API Token. For more information, see Getting Started with PubMatic APIs.


Info
For more information about "UAS Line Item Management Services," see Line Item Management Services (UAS).


Info
For more information about "Holding Inventory" in a line item, see Holding Inventory on a Line Item (UAS).


Info
For more information about "Wrapper Line Item and Working", see OpenWrap Integration.

Supported Operations

Info
titleImportant notes…
  • The following operations are not supported for PMP line item types except when using a GET Method.
  • PMP line items in Unified Ad Server are proxy presentations for deals created from PubMatic Private Marketplace.
  • To create PMP line item types, see Product APIs (For Publishers & Demand Partners) to create a deal.
  • You can associate wrapper line Item types only to third party creatives. Other creatives types (such as, native, text, and so on), cannot associate with wrapper line item types.


Service Name: /lineitems/

Method PathHTTP MethodDescriptionLink to Definition
/lineitems/POSTThis API method creates 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 order id.Retrieve the Details of a Line Item
/lineitems/GET

Retrieve a list of line items associated with your account.

You can also apply supported dimensions, filters, and sorting options to retrieve a list of line items with a specific set of details.

Info
Learn more about dimensions, sort, and filter options in Common Request Query Parameters.


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

This API method updates a single line item.  This method performs 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 the parameter is required, it will fail and the line item will not be updated.

Info
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 (for example, to change only the status of a line item).


Info

It is different than PUT, which replaces the entire object. PATCH updates only the object's dimensions specified in the request.


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

This API method deletes (archives) a line item.

Info
Archived line items are not used in ad serving.


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

This API method returns the line items targeted against the specified ad unit.
It returns a set of line items based on three parameters:

  • ron: returns the lineitems targeted against Run On Network (RON) ad units
  • direct: returns the line items targeted against a specified ad unit.
  • inherited: retrieves the set of parent ad units and returns the line items targeted against each of the parent ad units.
Getting the Line Items Targeted to an adUnit

Request Headers and Response Body Parameters

The following tables list all request headers and response body parameters used by the supported operations listed above.

Request Headers

Header nameType ValueRequiredDescription
Content-TypeStringapplication/jsonYesMedia type for request.
AuthorizationStringBearer ${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.

Info
For more information about access tokens, see 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, regional symbols and periods.

Name should be unique in context of an account.

A name you assign to a line item upon creation.
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 format. (For example, 2016-06-01T00:00:00)

Start date and time is the time at which a line item is expected to begin delivering. You can also pass "now" rather than passing an specific date if you want to start the line item ASAP.  The API sets the dates based on the following conditions:

  • If the order start date is already past, the line item start date defaults to the current date and time relative to the order's time zone.
  • If order start date is in the future, the line item start date should be greater than order start date and time relative to the order's time zone.

For example:

Code Block
{
  "startDate" : "now"
}


endDateStringNo

End date and time at which the line item is 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 format
For example, 2016-06-01T00:00:00

If user wants to create a line item which will run indefinitely, please do not pass this parameter.

Line item end date and time.
lineItemTypeIntegerYes

Should be valid and exist in the system.

Type of line item. You can retrieve the line item types using the Line Item Type API. Based on line item type, you have to select a valid goalType and goalPricing.

Line Item TypeGoal PricingGoal TypeGoal Unit Description
SponsorshipCPM/CPCImpressionsPercentage% of total impressions (0 to 100%)
StandardCPMImpressionsAbsoluteNumber of impressions
 CPCClicksAbsoluteNumber of clicks
HouseCPMImpressionsPercentage% of remaining impression
PMPCPMImpressionsPercentage% of remaining impressions
RTBCPMImpressionsPercentage% of remaining impressions
WrapperCPMNot ApplicableNot ApplicableGoal type and goal unit are not applicable


priorityIntegerYesThe type of line item determines the assigned priority. See table to the right.

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

Line Item TypePriority Range
Sponsorship1-4
Standard5-14
House13-16
Open Exchange8-16
Wrapper8-16
PMP5-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. When the creative gets linked to a line item, its status will be set to "Active." 

Status of the line item. You can retrieve the list of statuses using the Status API. The following statuses are supported for line items:                   

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

The system sets the line item to Active when user mapped the creatives to line item. This is only valid for guaranteed line items such as Standard, Sponsorship and House.

For Programmatic line items like Open Exchange and PMP, the status of line item set to Active once created as user can not map the creative to them.

Statuses "In Review", "Failed" and "Rejected" are very specific and applicable to PMP type of line items and the user can set it through the API. You can use "In Review", "Failed," and "Rejected" status to filter and search for line items having these statuses.

targetIntegerNoThis parameter is not consumed by API and is set by system internally.

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.

Info
See Line Item Targeting Services for more.


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.

paceIntegerNoShould be valid and exist in the system.

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 specified time period. This is the default value.
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.


Info
Default pace value for a standard line item type is 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%.
frequencyCapArray of Line Item Frequency Cap ObjectsNoOptionalFrequency 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
  • To create a line item without Scheduling, pass null value for schedules.
  • 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 as null;
    for example:

    Code Block
    { "dayOfWeek" : { "id" : null },  "timeStart" : "04:5:00", 
    "timeEnd" : "15:04:00", "timeZoneType" : "P" }

     

  • How can I schedule a line item to run on all days of the week with multiple time slots?

    Code Block
    { "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" }

     

  • timeZoneType: The API expects separate values for the time zone type. The client must send the same value across all schedules. Following is wrong (although the API is not validating it):
    Invalid Input: Timezone type must be same for all entries:

    Code Block
     { "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):

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

     

  • 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 value is "Evenly".

Creative Rotation is applicable 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
  • To create a line item without creatives, pass null value for creatives.
  • You must have at least one creative associated with a line item at any point in time, if the state is not in Draft.
  • If creative Rotation provided is Evenly or Optimized, null values should be passed for sequence and weight.

    Code Block
    {"creative": {"id": 14,"name": "Novartis 250x250",
    "url":"},

     

  • If creative Rotation is Sequential, sequence value should be passed. Weight can be null. No two sequence can be of same value except for sequence value 100.

    Code Block
    [{"creative": {"id": 14,"name": "Novartis 250x250","url":"},
    "sequence":2}, {"creative": {"id": 15,"name": "AMD 300x600-Test","url":"},
    "sequence":3}]

     

  • If creativeRotation is Weighted, non-null weight value should be passed. Sequence value will not be honored.

    Code Block
    [{"creative": {"id": 14,"name": "Novartis 250x250","url":"},"weight":20},
    {"creative": {"id": 15,"name": "AMD 300x600-Test","url":"},"weight":30}]

     

labelsList of Label ObjectsNoIf passed, labels should be valid and exist in the system.

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; for example, "excluded."

Pass an empty array to remove associated labels; that is, [ ]. Only inherited labels (if any) are 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 the account level currency. 

Info
Read-only attribute. It will be ignored If sent in requests. Attempting to change the value with a PUT/PATCH request returns a read-only attribute error.


isTestBooleanNo

Default is false

Enable isTest for a Guaranteed line item only during create and update processes. You cannot enable isTest for completed or archived line items.

isHeldBooleanNo

Default is false. Can be true / false. 

Enable the isHeld flag for Guaranteed line item types Standard and Sponsorship while creating or updating, if the line item is in Draft State.  

  • isHeld = true reserves inventory for targeted Ad Units against the specified goal while doing forecasting. By default, reserved inventory is considered as booked for two weeks from the date when line item is marked as Held. 
  • isHeld = false cancels reserved, booked inventory from Forecast.
Info
isHeld can be true only when the line item is in Draft state. When the line item is Active, the system automatically sets isHeld to false because Active state also reserves the inventory from the start through end date.


healthHealth ObjectNo.

Read Only param.

If passed in the request, will be ignored by API.

Health will help adOps/publisher understand, how lineitem is delivering currently based on its goal. They will get to know whether the lineItem is currently on track to meet its goal or not.

Currently, health will be calculated/shown for only Standard lineItems having pacing model as eve /front loaded with status in Active, InActive, Delivering, Completed, or Paused. Health object structure will be as follows:

Code Block
"health" : {
      "actualHealth" : 90,
      "expectedHealth" : 100,
      "deviation" : "10"
}

For lineItem with type other than Standard and Standard lineItems not having above mentioned status / pacing model, health object returned by API will be as follows :

Code Block
"health" : {
      "actualHealth" : 0,
      "expectedHealth" : 0,
      "deviation" : "N/A"
}

Currently, API does not support sorting or filtering on health parameter.

Status Transition Matrix

From To Who 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