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.

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

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

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

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

Supported Operations

Important 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 Path	HTTP Method	Description	Link to Definition
`/lineitems/`	`POST`	This API method creates one line item per request. This will be in transition.	Create a Line Item
`/lineitems/{id}`	`GET`	Retrieve 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. 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. 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). 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. 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
/updateStatus/{statusId}	PATCH	This API method is used to updateStatus of requested line items to a specific status	Update Status

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 name	Type	Value	Required	Description
Content-Type	String	application/json	Yes	Media type for request.
Authorization	String	Bearer ${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, see Getting Started with PubMatic APIs.

Request Body Parameters

Parameter Name Type Required Validations Descriptions

account

Integer

Yes

Account of the publisher for which this line item will be created.

Account of the Publisher

name

String

Yes

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.

order Integer Yes Should 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.

io String No Insertion order number should not be more than 255 characters. Insertion order details.

startDate

String

Yes

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:

{
  "startDate" : "now"
}

endDate

String

No

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.

lineItemType

Integer

Yes

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 Type	Goal Pricing	Goal Type	Goal Unit	Description
Sponsorship	CPM/CPC	Impressions	Percentage	% of total impressions (0 to 100%)
Standard	CPM	Impressions	Absolute	Number of impressions
	CPC	Clicks	Absolute	Number of clicks
House	CPM	Impressions	Percentage	% of remaining impression
PMP	CPM	Impressions	Percentage	% of remaining impressions
RTB	CPM	Impressions	Percentage	% of remaining impressions
Wrapper	CPM	Not Applicable	Not Applicable	Goal type and goal unit are not applicable

priority

Integer

Yes

The 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 Type	Priority Range
Sponsorship	1-4
Standard	5-14
House	13-16
Open Exchange	8-16
Wrapper	8-16
PMP	5-16

status

Integer

Yes

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:

Id	Name
1	Active
2	Inactive
4	Archived
5	Draft
7	Delivering
8	Paused
9	Completed
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.

target

Integer

No

This 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.

See Targeting Services for more.

goalPricing

Integer

Yes

It 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 Model	Description
1	CPM: Cost per thousand impressions
2	CPC: Cost per click

goal

Integer

Yes

Should 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).

goalType

Integer

Yes

Should 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 Type	Description
1	Impressions
2	Clicks

goalUnit

Integer

Yes

Should 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.

pace

Integer

No

Should 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 Id	Name	Description
1	Even	The ad server evenly distributes the delivery of impressions over specified time period. This is the default value.
2	ASAP	The ad server delivers impressions as quickly as possible until either the end date or the volume goal is met.
3	Front Loaded	Front loading defines how much to over pace line items at the beginning of flight.

Default pace value for a standard line item type is Even.

frontLoadPercent

Integer

No

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%.

frequencyCap Array of Line Item Frequency Cap Objects No Optional 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.

schedules

Array of Line Item Schedule Objects

No

Optional

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:
```
{ "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?

{ "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:

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

Valid values for timezonetype:
timeZoneType Value Description
P Publisher Time Zone
U User Time Zone
null (Not recommended) Publisher Time Zone

rate Double -up to 2 decimal places Yes Must be greater than or equal to 0 and less than or equal to 999999999.00 Represents the average rate (ecpm) of the selected line item.

creativeRotation

Integer

No

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.

Id	Name
1	Evenly
2	Sequential
3	Weighted
4	Optimized

creatives

Array of LineItem Creative Objects

No

Optional

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

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

labels

List of Label Objects

No

If 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.

currency

Currency Object

No

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.

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.

isTest

Boolean

No

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.

isHeld

Boolean

No

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.

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.

health

Health Object

No.

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:

"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 :

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

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

targeting

Map

No.

Values = valid target entity for the given key containing a list of targets.

Key set: "geo","os", "connectionType", "deviceType", "device", "deviceCapability", "browser", "browserLanguage", "inventory", "ipRange", "deviceScreenResolution", "hyperLocal", "hyperLocalDataSource", "zip", "customKey", "audiences"

Configuring geo targets sample example :

"geo": {
       "targets": [
           {
               "targetValue": 118205,
               "exclude": false,
               "targetLevel": 3
           },
           {
               "targetValue": 118206,
               "exclude": false,
               "targetLevel": 3
           }
       ]
   }

See Targeting Services for more information on how to target different set of targetings.

To remove all targetings set at lineitem level, pass targeting object as follows in the request :

{
....
"targeting": {}
}

Passing null value for targeting is not allowed and API will throw an error as it is ambiguous.

On 'date' you have to list all targeting types in the request JSON. Add empty targets:[ ] if that targeting type is not intended. If any targeting is missing in json it will give validation error. This is done for simplicity and consistency with configuration protocol.
API is Transactional, which means that if there is a failure in any of the targeting nothing should be saved.
At a granular level each targeting should contain only the three parameters {targetValue, targetLevel, exclude}. If any extra parameter is preset in the post body during update / create is given, will result in an error.

Status Transition Matrix

From	To	Who does it?	Condition
Draft	Active	System	As soon as line item has at least one Creative.
Draft	Archived	User
Active	Delivering	System	As soon as the line item starts Delivering.
Active	Inactive	User
Active	Paused	User
Delivering	Paused	User
Delivering	Inactive	User
Paused	Active	User
Paused	Inactive	User
Paused	Archived	User
Inactive	Active	User
Inactive	Archived	User
Completed	Archived	User
Archived	Not allowed	User	Note: It is no longer permitted to change "Archived" to "Inactive."

Status and Editable Fields Matrix

Operations and Samples

The following sections describe the line item API operations and provide sample code to demonstrate usage. Unless otherwise noted in the operation definition, each operation uses the request headers and request body parameters listed above.

Line Item can be created with targeting information as well.

Create a Line Item

This API enables the creation of a line item.

While creating a line items with isHeld = true, the system populates heldStartDate with the current UTC date. If isHeld is set to false, heldStartDate will be set to null. Do not pass heldStartDate as request input during a create operation. During update operation, do not update the heldStartDate.

Request

URI	HTTP Method
https://api.pubmatic.com/v1/uas/lineitems/	POST

Notes:

See Request Headers above for request header requirements.
See Request Body Parameters for parameters available to use in this request.

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": [],
	"isHeld": true,
	"targeting": {
        "audience": {
            "targets": [
                {
                    "targetValue": 26206,
                    "exclude": false,
                    "targetLevel": 1,
                    "name": "Test Audience for 130917",
                    "dataProviderId": 117,
                    "dataProviderName": "Test DP For 130917",
                    "enabled": 0
                }
            ]
        },
        "browser": {
            "targets": [
                {
                    "targetValue": 1,
                    "exclude": true,
                    "targetLevel": 1,
                    "name": "IE"
                },
                {
                    "targetValue": 6,
                    "exclude": true,
                    "targetLevel": 1,
                    "name": "IEMobile"
                }
            ]
        },
        "browserLanguage": {
            "targets": [
                {
                    "targetValue": 1,
                    "exclude": true,
                    "targetLevel": 1,
                    "name": "Afrikaans"
                },
                {
                    "targetValue": 2,
                    "exclude": true,
                    "targetLevel": 1,
                    "name": "Aragonese"
                },
                {
                    "targetValue": 3,
                    "exclude": true,
                    "targetLevel": 1,
                    "name": "Arabic"
                }
            ]
        },
        "connectionType": {
            "targets": [
                {
                    "targetValue": 1,
                    "exclude": false,
                    "targetLevel": 1,
                    "name": "Cellular"
                },
                {
                    "targetValue": 2,
                    "exclude": false,
                    "targetLevel": 1,
                    "name": "WiFi"
                }
            ]
        },
        "customKey": {
            "targets": [
                {
                    "targetValue": {
                        "customKey": {
                            "id": 56,
                            "name": "RD_Age",
                            "status": {
                                "id": 1
                            }
                        },
                        "operator": {
                            "id": 1,
                            "name": "IS"
                        },
                        "customValue": {
                            "value": "21"
                        },
                        "groupId": 1,
                        "setId": 1
                    },
                    "exclude": false,
                    "targetLevel": 1
                },
                {
                    "targetValue": {
                        "customKey": {
                            "id": 118,
                            "name": "RD_Color",
                            "status": {
                                "id": 1
                            }
                        },
                        "operator": {
                            "id": 1,
                            "name": "IS"
                        },
                        "customValue": {
                            "value": "Saffron"
                        },
                        "groupId": 2,
                        "setId": 1
                    },
                    "exclude": false,
                    "targetLevel": 1
                },
                {
                    "targetValue": {
                        "customKey": {
                            "id": 56,
                            "name": "RD_Age",
                            "status": {
                                "id": 1
                            }
                        },
                        "operator": {
                            "id": 1,
                            "name": "IS"
                        },
                        "customValue": {
                            "value": "27"
                        },
                        "groupId": 1,
                        "setId": 2
                    },
                    "exclude": false,
                    "targetLevel": 1
                }
            ]
        },
        "device": {
            "targets": [
                {
                    "targetValue": 8,
                    "exclude": false,
                    "targetLevel": 1,
                    "deviceTypeId": 3,
                    "deviceValue": "Samsung",
                    "make": "Samsung"
                }
            ]
        },
        "deviceCapability": {
            "targets": [
                {
                    "targetValue": 6,
                    "exclude": false,
                    "targetLevel": 1,
                    "deviceCapabilityId": 6,
                    "deviceCapabilityName": "NFC support"
                },
                {
                    "targetValue": 5,
                    "exclude": false,
                    "targetLevel": 1,
                    "deviceCapabilityId": 5,
                    "deviceCapabilityName": "Touchscreen support"
                }
            ]
        },
        "deviceType": {
            "targets": [
                {
                    "targetValue": 2,
                    "exclude": false,
                    "targetLevel": 1,
                    "deviceTypeId": 2,
                    "deviceType": "Smart Phone"
                },
                {
                    "targetValue": 1,
                    "exclude": false,
                    "targetLevel": 1,
                    "deviceTypeId": 1,
                    "deviceType": "Feature Phone"
                }
            ]
        },
        "geo": {
            "targets": [
                {
                    "targetValue": 107,
                    "exclude": false,
                    "targetLevel": 1,
                    "countryCode": "IN",
                    "name": "India"
                }
            ]
        },
        "hyperLocal": {
            "targets": [
                {
                    "targetValue": {
                        "latitude": 18.5493274,
                        "longitude": 73.7864383,
                        "radius": 11,
                        "radiusInKm": 11,
                        "radiusUnit": "km"
                    },
                    "exclude": false
                }
            ]
        },
        "hyperLocalDataSource": {
            "targets": [
                {
                    "targetValue": 1,
                    "exclude": false,
                    "targetLevel": 1
                }
            ]
        },
        "inventory": {
            "targets": [
                {
                    "targetValue": 10015725,
                    "exclude": false,
                    "targetLevel": 2,
                    "name": "RD_AU_13th_March"
                },
                {
                    "targetValue": 10015724,
                    "exclude": false,
                    "targetLevel": 2,
                    "name": "SM_Test_12_Mar"
                }
            ]
        },
        "ipRange": {
            "targets": [
                {
                    "targetValue": {
                        "from": "10.110.205.61",
                        "to": "10.110.205.65"
                    },
                    "exclude": false,
                    "targetLevel": 1
                },
                {
                    "targetValue": {
                        "from": "10.110.205.71",
                        "to": "10.110.205.75"
                    },
                    "exclude": false,
                    "targetLevel": 1
                }
            ]
        },
        "os": {
            "targets": [
                {
                    "targetValue": 6,
                    "exclude": false,
                    "targetLevel": 1,
                    "osTypeId": 1,
                    "osName": "iOS"
                },
                {
                    "targetValue": 11,
                    "exclude": false,
                    "targetLevel": 1,
                    "osTypeId": 2,
                    "osName": "Android"
                }
            ]
        },
        "zip": {}
    }
}

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": "http://$URI_PREFIX/{apiVersion}/phoenix"
  },
  "io": "12",
  "startDate": "2016-01-20T00:00:00",
  "endDate": "2016-01-20T00:00:00",
  "lineItemType": {
      "id": 2,
      "name": "Standard",
      "url": "http://$URI_PREFIX/{apiVersion}/phoenix/lineitemtypes/2"
  },
  "priority": 6,
  "status": {
      "id": 5,
      "name": "Draft",
      "url": "http://$URI_PREFIX/{apiVersion}/phoenix/status/5"
  },  "target": {
      "id": 1556,
      "isPreset": 0,
      "url": "http://$URI_PREFIX/{apiVersion}/phoenix"
  },  "pace": {
      "id": 1,
      "name": "Even",
      "url": "http://$URI_PREFIX/{apiVersion}/phoenix/lineitempaces/1"
  },  "user": {
      "id": 18280,
      "url": "http://$URI_PREFIX/{apiVersion}/phoenix/users/18280"
  },  "goalType": {
      "id": 1,
      "name": "Impressions",
      "url": "http://$URI_PREFIX/{apiVersion}/phoenix/goaltypes/1"
  },  "goalUnit": {
      "id": 1,
      "name": "Absolute",
      "url": "http://$URI_PREFIX/{apiVersion}/phoenix/goalunits/1"
  },  "goalPricing": {
      "id": 1,
      "name": "CPM",
      "url": "http://$URI_PREFIX/{apiVersion}/phoenix/goalpricing/1"
  },  "isTest": false,
  "goal": 1230.0000000000,
  "labels": [{
       "id": 2,
       "name": "Label-2",
       "account": {
            "id": 118385,
            "url": "http://$URI_PREFIX/{apiVersion}/phoenix"
       },
       "labelType": {
            "id": 1,
            "name": "Ad Exclusion",
            "url": "http://$URI_PREFIX/{apiVersion}/phoenix/labeltype/1"
       },
       "isInherited": false  }],
  "schedules": [{
       "timeStart": "01:00:00",
       "timeEnd": "04:00:59",
       "timeZoneType": "U"  }],
  "rate": 12.0000000000,
  "frequencyCaps": [{
       "frequencyCapPeriod": {
            "id": 1,
            "url":"http://$URI_PREFIX/{apiVersion}/phoenix/frequencycapperiods/1"
       },
       "capValue": 123,
       "periodValue": 1
  }],
  "creativeRotation": {
       "id": 1,
       "name": "Evenly",
       "url": "http://$URI_PREFIX/{apiVersion}/phoenix/creativerotations/1"
  },
  "updatedAt": 1538015619000,
  "createdAt": 1534906964000,
  "timeZone": {
       "id": 1,
       "url": "http://$URI_PREFIX/{apiVersion}/phoenix/timezones/1"
  },
  "createdBy": {
       "id": 18280,
       "url": "http://$URI_PREFIX/{apiVersion}/phoenix/users/18280"
  }, "isHeld": true, "heldStartDate": "2016-01-20T01:03:30",
 "health" : {
       "actualHealth" : 90,
       "expectedHealth" : 100,
       "deviation" : "10"
  },
	"targeting": {
        "audience": {
            "targets": [
                {
                    "targetValue": 26206,
                    "exclude": false,
                    "targetLevel": 1,
                    "name": "Test Audience for 130917",
                    "dataProviderId": 117,
                    "dataProviderName": "Test DP For 130917",
                    "enabled": 0
                }
            ]
        },
        "browser": {
            "targets": [
                {
                    "targetValue": 1,
                    "exclude": true,
                    "targetLevel": 1,
                    "name": "IE"
                },
                {
                    "targetValue": 6,
                    "exclude": true,
                    "targetLevel": 1,
                    "name": "IEMobile"
                }
            ]
        },
        "browserLanguage": {
            "targets": [
                {
                    "targetValue": 1,
                    "exclude": true,
                    "targetLevel": 1,
                    "name": "Afrikaans"
                },
                {
                    "targetValue": 2,
                    "exclude": true,
                    "targetLevel": 1,
                    "name": "Aragonese"
                },
                {
                    "targetValue": 3,
                    "exclude": true,
                    "targetLevel": 1,
                    "name": "Arabic"
                }
            ]
        },
        "connectionType": {
            "targets": [
                {
                    "targetValue": 1,
                    "exclude": false,
                    "targetLevel": 1,
                    "name": "Cellular"
                },
                {
                    "targetValue": 2,
                    "exclude": false,
                    "targetLevel": 1,
                    "name": "WiFi"
                }
            ]
        },
        "customKey": {
            "targets": [
                {
                    "targetValue": {
                        "customKey": {
                            "id": 56,
                            "name": "RD_Age",
                            "status": {
                                "id": 1
                            }
                        },
                        "operator": {
                            "id": 1,
                            "name": "IS"
                        },
                        "customValue": {
                            "value": "21"
                        },
                        "groupId": 1,
                        "setId": 1
                    },
                    "exclude": false,
                    "targetLevel": 1
                },
                {
                    "targetValue": {
                        "customKey": {
                            "id": 118,
                            "name": "RD_Color",
                            "status": {
                                "id": 1
                            }
                        },
                        "operator": {
                            "id": 1,
                            "name": "IS"
                        },
                        "customValue": {
                            "value": "Saffron"
                        },
                        "groupId": 2,
                        "setId": 1
                    },
                    "exclude": false,
                    "targetLevel": 1
                },
                {
                    "targetValue": {
                        "customKey": {
                            "id": 56,
                            "name": "RD_Age",
                            "status": {
                                "id": 1
                            }
                        },
                        "operator": {
                            "id": 1,
                            "name": "IS"
                        },
                        "customValue": {
                            "value": "27"
                        },
                        "groupId": 1,
                        "setId": 2
                    },
                    "exclude": false,
                    "targetLevel": 1
                }
            ]
        },
        "device": {
            "targets": [
                {
                    "targetValue": 8,
                    "exclude": false,
                    "targetLevel": 1,
                    "deviceTypeId": 3,
                    "deviceValue": "Samsung",
                    "make": "Samsung"
                }
            ]
        },
        "deviceCapability": {
            "targets": [
                {
                    "targetValue": 6,
                    "exclude": false,
                    "targetLevel": 1,
                    "deviceCapabilityId": 6,
                    "deviceCapabilityName": "NFC support"
                },
                {
                    "targetValue": 5,
                    "exclude": false,
                    "targetLevel": 1,
                    "deviceCapabilityId": 5,
                    "deviceCapabilityName": "Touchscreen support"
                }
            ]
        },
        "deviceType": {
            "targets": [
                {
                    "targetValue": 2,
                    "exclude": false,
                    "targetLevel": 1,
                    "deviceTypeId": 2,
                    "deviceType": "Smart Phone"
                },
                {
                    "targetValue": 1,
                    "exclude": false,
                    "targetLevel": 1,
                    "deviceTypeId": 1,
                    "deviceType": "Feature Phone"
                }
            ]
        },
        "geo": {
            "targets": [
                {
                    "targetValue": 107,
                    "exclude": false,
                    "targetLevel": 1,
                    "countryCode": "IN",
                    "name": "India"
                }
            ]
        },
        "hyperLocal": {
            "targets": [
                {
                    "targetValue": {
                        "latitude": 18.5493274,
                        "longitude": 73.7864383,
                        "radius": 11,
                        "radiusInKm": 11,
                        "radiusUnit": "km"
                    },
                    "exclude": false
                }
            ]
        },
        "hyperLocalDataSource": {
            "targets": [
                {
                    "targetValue": 1,
                    "exclude": false,
                    "targetLevel": 1
                }
            ]
        },
        "inventory": {
            "targets": [
                {
                    "targetValue": 10015725,
                    "exclude": false,
                    "targetLevel": 2,
                    "name": "RD_AU_13th_March"
                },
                {
                    "targetValue": 10015724,
                    "exclude": false,
                    "targetLevel": 2,
                    "name": "SM_Test_12_Mar"
                }
            ]
        },
        "ipRange": {
            "targets": [
                {
                    "targetValue": {
                        "from": "10.110.205.61",
                        "to": "10.110.205.65"
                    },
                    "exclude": false,
                    "targetLevel": 1
                },
                {
                    "targetValue": {
                        "from": "10.110.205.71",
                        "to": "10.110.205.75"
                    },
                    "exclude": false,
                    "targetLevel": 1
                }
            ]
        },
        "os": {
            "targets": [
                {
                    "targetValue": 6,
                    "exclude": false,
                    "targetLevel": 1,
                    "osTypeId": 1,
                    "osName": "iOS"
                },
                {
                    "targetValue": 11,
                    "exclude": false,
                    "targetLevel": 1,
                    "osTypeId": 2,
                    "osName": "Android"
                }
            ]
        },
        "zip": {}
    }
 }

Retrieve the Details of a Line Item

This API lets you retrieve the details of a line item.

Request

URI	HTTP Method
https://api.pubmatic.com/v1/uas/lineitems/{id}	GET

Notes:

See Request Headers above for request header requirements.
See Request Body Parameters for parameters available to use in this request.

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://$URI_PREFIX/{apiVersion}/phoenix"
  },
  "name": "Test-Line-Item",
  "description": "Test LineItem",
  "order": {
      "id": 6,
      "name": "HOTestOrder",
      "url": "http://$URI_PREFIX/{apiVersion}/phoenix"
  },
  "io": "12",
  "startDate": "2016-01-20T00:00:00",
  "endDate": "2016-01-20T00:00:00",
  "lineItemType": {
      "id": 2,
      "name": "Standard",
      "url": "http://$URI_PREFIX/{apiVersion}/phoenix/lineitemtypes/2"
  },
  "priority": 6,
  "status": {
      "id": 5,
      "name": "Draft",
      "url": "http://$URI_PREFIX/{apiVersion}/phoenix/status/5"
  },
  "target": {
      "id": 1556,
      "isPreset": 0,
      "url": "http://$URI_PREFIX/{apiVersion}/phoenix"
  },
  "pace": {
      "id": 1,
      "name": "Even",
      "url": "http://$URI_PREFIX/{apiVersion}/phoenix/lineitempaces/1"
  },
  "user": {
     "id": 18280,
     "url": "http://$URI_PREFIX/{apiVersion}/phoenix/users/18280"
  },
  "goalType": { "id": 1,
     "name": "Impressions",
     "url": "http://$URI_PREFIX/{apiVersion}/phoenix/goaltypes/1"
  },
  "goalUnit": {
     "id": 1,
     "name": "Absolute",
     "url": "http://$URI_PREFIX/{apiVersion}/phoenix/goalunits/1"
  },
  "goalPricing": {
      "id": 1,
      "name": "CPM",
      "url": "http://$URI_PREFIX/{apiVersion}/phoenix/goalpricing/1"
  },
  "isTest": false, "goal": 1230.0000000000,
  "labels": [{
     "id": 2,
     "name": "Label-2",
     "account": {
        "id": 118385,
        "url": "http://$URI_PREFIX/{apiVersion}/phoenix"
     },
     "labelType": {
        "id": 1,
        "name": "Ad Exclusion",
        "url": "http://$URI_PREFIX/{apiVersion}/phoenix/labeltype/1"
     },
     "isInherited": false
  }],
  "schedules": [{
     "timeStart": "01:00:00",
     "timeEnd": "04:00:59",
     "timeZoneType": "U"
  }],
  "rate": 12.0000000000,
  "frequencyCaps": [{
     "frequencyCapPeriod": {
          "id": 1,
          "url":"http://$URI_PREFIX/{apiVersion}/phoenix/frequencycapperiods/1
     },
     "capValue": 123,
     "periodValue": 1
  }],
  "creativeRotation": {
     "id": 1,
     "name": "Evenly",
     "url": "http://$URI_PREFIX/{apiVersion}/phoenix/creativerotations/1"
  },
  "updatedAt": 1538015619000,
  "createdAt": 1534906964000,
  "timeZone": {
     "id": 1,
     "url": "http://$URI_PREFIX/{apiVersion}/phoenix/timezones/1"
  },
 "createdBy": {
     "id": 18280,
     "url": "http://$URI_PREFIX/{apiVersion}/phoenix/users/18280"
  },
  "isHeld": true,
  "heldStartDate": "2016-01-20T01:03:30",
  "health" : {
     "actualHealth" : 90,
     "expectedHealth" : 100,
     "deviation" : "10"
 },
 "targeting": {
        "audience": {
            "targets": [
                {
                    "targetValue": 26206,
                    "exclude": false,
                    "targetLevel": 1,
                    "name": "Test Audience for 130917",
                    "dataProviderId": 117,
                    "dataProviderName": "Test DP For 130917",
                    "enabled": 0
                }
            ]
        },
        "browser": {
            "targets": [
                {
                    "targetValue": 1,
                    "exclude": true,
                    "targetLevel": 1,
                    "name": "IE"
                },
                {
                    "targetValue": 6,
                    "exclude": true,
                    "targetLevel": 1,
                    "name": "IEMobile"
                }
            ]
        },
        "browserLanguage": {
            "targets": [
                {
                    "targetValue": 1,
                    "exclude": true,
                    "targetLevel": 1,
                    "name": "Afrikaans"
                },
                {
                    "targetValue": 2,
                    "exclude": true,
                    "targetLevel": 1,
                    "name": "Aragonese"
                },
                {
                    "targetValue": 3,
                    "exclude": true,
                    "targetLevel": 1,
                    "name": "Arabic"
                }
            ]
        },
        "connectionType": {
            "targets": [
                {
                    "targetValue": 1,
                    "exclude": false,
                    "targetLevel": 1,
                    "name": "Cellular"
                },
                {
                    "targetValue": 2,
                    "exclude": false,
                    "targetLevel": 1,
                    "name": "WiFi"
                }
            ]
        },
        "customKey": {
            "targets": [
                {
                    "targetValue": {
                        "customKey": {
                            "id": 56,
                            "name": "RD_Age",
                            "status": {
                                "id": 1
                            }
                        },
                        "operator": {
                            "id": 1,
                            "name": "IS"
                        },
                        "customValue": {
                            "value": "21"
                        },
                        "groupId": 1,
                        "setId": 1
                    },
                    "exclude": false,
                    "targetLevel": 1
                },
                {
                    "targetValue": {
                        "customKey": {
                            "id": 118,
                            "name": "RD_Color",
                            "status": {
                                "id": 1
                            }
                        },
                        "operator": {
                            "id": 1,
                            "name": "IS"
                        },
                        "customValue": {
                            "value": "Saffron"
                        },
                        "groupId": 2,
                        "setId": 1
                    },
                    "exclude": false,
                    "targetLevel": 1
                },
                {
                    "targetValue": {
                        "customKey": {
                            "id": 56,
                            "name": "RD_Age",
                            "status": {
                                "id": 1
                            }
                        },
                        "operator": {
                            "id": 1,
                            "name": "IS"
                        },
                        "customValue": {
                            "value": "27"
                        },
                        "groupId": 1,
                        "setId": 2
                    },
                    "exclude": false,
                    "targetLevel": 1
                }
            ]
        },
        "device": {
            "targets": [
                {
                    "targetValue": 8,
                    "exclude": false,
                    "targetLevel": 1,
                    "deviceTypeId": 3,
                    "deviceValue": "Samsung",
                    "make": "Samsung"
                }
            ]
        },
        "deviceCapability": {
            "targets": [
                {
                    "targetValue": 6,
                    "exclude": false,
                    "targetLevel": 1,
                    "deviceCapabilityId": 6,
                    "deviceCapabilityName": "NFC support"
                },
                {
                    "targetValue": 5,
                    "exclude": false,
                    "targetLevel": 1,
                    "deviceCapabilityId": 5,
                    "deviceCapabilityName": "Touchscreen support"
                }
            ]
        },
        "deviceType": {
            "targets": [
                {
                    "targetValue": 2,
                    "exclude": false,
                    "targetLevel": 1,
                    "deviceTypeId": 2,
                    "deviceType": "Smart Phone"
                },
                {
                    "targetValue": 1,
                    "exclude": false,
                    "targetLevel": 1,
                    "deviceTypeId": 1,
                    "deviceType": "Feature Phone"
                }
            ]
        },
        "geo": {
            "targets": [
                {
                    "targetValue": 107,
                    "exclude": false,
                    "targetLevel": 1,
                    "countryCode": "IN",
                    "name": "India"
                }
            ]
        },
        "hyperLocal": {
            "targets": [
                {
                    "targetValue": {
                        "latitude": 18.5493274,
                        "longitude": 73.7864383,
                        "radius": 11,
                        "radiusInKm": 11,
                        "radiusUnit": "km"
                    },
                    "exclude": false
                }
            ]
        },
        "hyperLocalDataSource": {
            "targets": [
                {
                    "targetValue": 1,
                    "exclude": false,
                    "targetLevel": 1
                }
            ]
        },
        "inventory": {
            "targets": [
                {
                    "targetValue": 10015725,
                    "exclude": false,
                    "targetLevel": 2,
                    "name": "RD_AU_13th_March"
                },
                {
                    "targetValue": 10015724,
                    "exclude": false,
                    "targetLevel": 2,
                    "name": "SM_Test_12_Mar"
                }
            ]
        },
        "ipRange": {
            "targets": [
                {
                    "targetValue": {
                        "from": "10.110.205.61",
                        "to": "10.110.205.65"
                    },
                    "exclude": false,
                    "targetLevel": 1
                },
                {
                    "targetValue": {
                        "from": "10.110.205.71",
                        "to": "10.110.205.75"
                    },
                    "exclude": false,
                    "targetLevel": 1
                }
            ]
        },
        "os": {
            "targets": [
                {
                    "targetValue": 6,
                    "exclude": false,
                    "targetLevel": 1,
                    "osTypeId": 1,
                    "osName": "iOS"
                },
                {
                    "targetValue": 11,
                    "exclude": false,
                    "targetLevel": 1,
                    "osTypeId": 2,
                    "osName": "Android"
                }
            ]
        },
        "zip": {}
    }
}

Retrieve a List of Line Items

This API lets you retrieve a list of a line item. You can also apply supported dimensions, filters, and sorting options to retrieve a list with a specific set of details according to your requirements.

See Common Request Query Parameters for more information about using dimensions, filters, and sorting.

Request

URI	HTTP Method
https://api.pubmatic.com/v1/uas/lineitems/	GET

Notes:

See Request Headers above for request header requirements.
See Request Body Parameters for parameters available to use in this request.

Sample Request URL

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

Response

This will return a list of supported line item types.

Update a Line Item

This API lets you update a line item.

The createdBy field gets populated on line item creation and is never updated. The heldStartDate field defaults to null until the first time the line item is marked as held by an update operation, which triggers the system to internally populate the field with current Date in UTC as value.

Request

URI	HTTP Method
https://api.pubmatic.com/v1/uas/lineitems/	PUT

Notes:

See Request Headers above for request header requirements.
See Request Body Parameters for parameters available to use in this request.

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": [],
    "isHeld": true,
	"targeting": {
        "audience": {},
        "browser": {},
        "browserLanguage": {},
        "connectionType": {},
        "customKey": {},
        "device": {},
        "deviceCapability": {},
        "deviceType": {},
        "geo": {},
        "hyperLocal": {},
        "hyperLocalDataSource": {},
        "inventory": {
            "targets": [
                {
                    "targetValue": 10016221,
                    "exclude": false,
                    "targetLevel": 2,
                    "name": "RD_AU_Goal_2"
                }
            ]
        },
        "ipRange": {},
        "os": {},
        "zip": {}
    }
 }

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": "http://$URI_PREFIX/{apiVersion}/phoenix"
  },
  "io": "12",  "startDate": "2016-01-20T00:00:00",
  "endDate": "2016-01-20T00:00:00",  "lineItemType": {
    "id": 2,
    "name": "Standard",
    "url": "http://$URI_PREFIX/{apiVersion}/phoenix/lineitemtypes/2"
  },
  "priority": 6,
  "status": {
    "id": 5,
    "name": "Draft",
    "url": "http://$URI_PREFIX/{apiVersion}/phoenix/status/5"  },
  "target": {
    "id": 1556,
    "isPreset": 0,
    "url": "http://$URI_PREFIX/{apiVersion}/phoenix"
  },  "isTest": true,
  "pace": {
    "id": 1,
    "name": "Even",
    "url": "http://$URI_PREFIX/{apiVersion}/phoenix/lineitempaces/1"
  },
  "user": {
    "id": 18280,
    "url": "http://$URI_PREFIX/{apiVersion}/phoenix/users/18280"
  },
  "goalType": {
    "id": 1,
    "name": "Impressions",
    "url": "http://$URI_PREFIX/{apiVersion}/phoenix/goaltypes/1"
  },
  "goalUnit": {
    "id": 1,
    "name": "Absolute",
    "url": "http://$URI_PREFIX/{apiVersion}/phoenix/goalunits/1"
  },
  "goalPricing": {
    "id": 1,
    "name": "CPM",
    "url": "http://$URI_PREFIX/{apiVersion}/phoenix/goalpricing/1"
  },
  "goal": 1200.0000000000,
  "labels": [{
    "id": 2,
    "name": "Label-2",
    "account": {
         "id": 118385,
         "url": "http://$URI_PREFIX/{apiVersion}/phoenix"
    },
    "labelType": {
         "id": 1,
         "name": "Ad Exclusion",
         "url": "http://$URI_PREFIX/{apiVersion}/phoenix/labeltype/1"
    },
    "isInherited": false
  }],
  "schedules": [{
    "timeStart": "01:00:00",
    "timeEnd": "04:00:59",
    "timeZoneType": "U"
  }],
  "rate": 12.0000000000,
  "frequencyCaps": [{
    "frequencyCapPeriod": {
         "id": 1,
         "url":"http://$URI_PREFIX/{apiVersion}/phoenix/frequencycapperiods/1"
    },
    "capValue": 123,
    "periodValue": 1
  }],
  "creativeRotation": {
    "id": 1,
    "name": "Evenly",
    "url": "http://$URI_PREFIX/{apiVersion}/phoenix/creativerotations/1"
  },
  "updatedAt": 1538015619000,
  "createdAt": 1534906964000,
  "timeZone": {
    "id": 1,
    "url": "http://$URI_PREFIX/{apiVersion}/phoenix/timezones/1"
  },
  "createdBy": {
    "id": 18280,
    "url": "http://$URI_PREFIX/{apiVersion}/phoenix/users/18280"
  },
  "isHeld": true,
  "heldStartDate": "2016-01-20T01:03:30",
  "health" : {
    "actualHealth" : 90,
    "expectedHealth" : 100,
    "deviation" : "10"
  },
  "targeting": {
        "audience": {},
        "browser": {},
        "browserLanguage": {},
        "connectionType": {},
        "customKey": {},
        "device": {},
        "deviceCapability": {},
        "deviceType": {},
        "geo": {},
        "hyperLocal": {},
        "hyperLocalDataSource": {},
        "inventory": {
            "targets": [
                {
                    "targetValue": 10016221,
                    "exclude": false,
                    "targetLevel": 2,
                    "name": "RD_AU_Goal_2"
                }
            ]
        },
        "ipRange": {},
        "os": {},
        "zip": {}
    }
 }

Update (Patch) a Line Item

This API lets you update (Patch) a line item. Only the attributes passed in the request will be updated.

Request

URI	HTTP Method
https://api.pubmatic.com/v1/uas/lineitems/	PATCH

Notes:

See Request Headers above for request header requirements.
See Request Body Parameters for parameters available to use in this request.

Sample Request URL

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

Sample Request JSON

{
  "description": "Test Line Item Patch"
}

Response

Sample Response JSON

{
	 "id": 1538,
	 "account": {
			"id": 118385,
			"name": "PubMatic Inc.",
			"url": "http://$URI_PREFIX/{apiVersion}/phoenix"  
	},
	"name": "Test-Line-Item",
	"description": "Test Line Item Patch",
	"order": {
		"id": 6,
		"name": "HOTestOrder",
		"url": "http://$URI_PREFIX/{apiVersion}/phoenix"  
	},
	"io": "12",
	"startDate": "2016-01-20T00:00:00",
	"endDate": "2016-01-20T00:00:00",
	"lineItemType": {
		"id": 2,
		"name": "Standard",
		"url": "http://$URI_PREFIX/{apiVersion}/phoenix/lineitemtypes/2"  
	},
	"priority": 6,
	"status": {
		"id": 5,
		"name": "Draft",
		"url": "http://$URI_PREFIX/{apiVersion}/phoenix/status/5"  
	},
	"target": {
		"id": 1556,
		"isPreset": 0,
		"url": "http://$URI_PREFIX/{apiVersion}/phoenix"  
	},
	"pace": {
		"id": 1,
		"name": "Even",
		"url": "http://$URI_PREFIX/{apiVersion}/phoenix/lineitempaces/1"  
	},
	"user": {
		"id": 18280,
		"url": "http://$URI_PREFIX/{apiVersion}/phoenix/users/18280"  
	},
	"goalType": {
		"id": 1,
		"name": "Impressions",
		"url": "http://$URI_PREFIX/{apiVersion}/phoenix/goaltypes/1"  
	},
	"goalUnit": {
		"id": 1,
		"name": "Absolute",
		"url": "http://$URI_PREFIX/{apiVersion}/phoenix/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://$URI_PREFIX/{apiVersion}/phoenix"      
		},
		"labelType": {
			"id": 1,
			"name": "Ad Exclusion",
			"url": "http://$URI_PREFIX/{apiVersion}/phoenix/labeltype/1"      
		},
		"isInherited": false  
	}],
	"schedules": [{
		"timeStart": "01:00:00",
		"timeEnd": "04:00:59",
		"timeZoneType": "U"  
	}],
	"rate": 12.0000000000,
	"frequencyCaps": [{
		"frequencyCapPeriod": {
			"id": 1,
			"url":"http://$URI_PREFIX/{apiVersion}/phoenix/frequencycapperiods/1"      
		},
		"capValue": 123,
		"periodValue": 1  
	}],
	"creativeRotation": {
		"id": 1,
		"name": "Evenly",
		"url": "http://$URI_PREFIX/{apiVersion}/phoenix/creativerotations/1"  
	},
	"isTest": true,
	"updatedAt": 1538015619000,
	"createdAt": 1534906964000,
	"timeZone": {
		"id": 1,
		"url": "http://$URI_PREFIX/{apiVersion}/phoenix/timezones/1"  
	},
	"createdBy": {
		"id": 18280,
		"url": "http://$URI_PREFIX/{apiVersion}/phoenix/users/18280"
	},
	"isHeld": true,
	"heldStartDate": "2016-01-20T01:03:30",
	"health": {
		"actualHealth": 90,
		"expectedHealth": 100,
		"deviation": "10"  
	},
	"targeting": {
        "audience": {},
        "browser": {},
        "browserLanguage": {},
        "connectionType": {},
        "customKey": {},
        "device": {},
        "deviceCapability": {},
        "deviceType": {},
        "geo": {},
        "hyperLocal": {},
        "hyperLocalDataSource": {},
        "inventory": {
            "targets": [
                {
                    "targetValue": 10016221,
                    "exclude": false,
                    "targetLevel": 2,
                    "name": "RD_AU_Goal_2"
                }
            ]
        },
        "ipRange": {},
        "os": {},
        "zip": {}
    }
}

Delete a Line Item

This API lets you delete (archive) a line item.

Request

URI	HTTP Method
https://api.pubmatic.com/v1/uas/lineitems/{lineitemid}	DELETE

See Request Headers above for request header requirements.

Sample Request URL

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

Response

Sample Response

Returns 'true' if archive is successful; 'false' if unsuccessful.

Getting the Line Items Targeted to an adUnit

This API method returns the line items targeted against the specified adUnit, based on three parameters:

ron: returns the lineitems targeted against 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.

Request

URI	HTTP Method
https://$URI_PREFIX/{apiVersion}/phoenix/lineitems/adunit/{adUnitId}	GET

Notes:

See Request Headers above for request header requirements.
See Request Body Parameters for parameters available to use in this request.

AdUnit Targeted LineItems Dimensions

See Common Request Query Parameters > Supported Dimensions to learn more.

Sort Functionality

By default, startDate and endDate display in lineItem level timeZone.

See Common Request Query Parameters > Sort Functionality to learn more.

Getting the Line Items Targeted to adUnit

Returns the list of lineItems targeted against the specified adUnit.

Query Parameter	Type	Required	Validations	Description
`ron`	boolean	No	Default false if no query param is specified. Allowed values are true and false.	If true, the lineItems that are targeted against RON adUnit are returned.
`inherited`	boolean	No	Default false if no query param is specified. Allowed values are true and false.	If true, gets the parent hierarchy of adUnit and lists the lineItems that are targeted to each of the adUnit in parent hierarchy.
`direct`	boolean	No	Default false if no query param is specified. Allowed values are true and false.	If true, the lineItems that are directly targeted against the specified adUnit are returned.

By default, if no flag is passed, all the query params are true. If one of the flags is set to true, other query params are false by default.

Sample Request URL

https://$URI_PREFIX/{apiVersion}/phoenix/lineitems/adunit/{adUnitId}

Response

Sample Response JSON

{
	"metaData": {
		"totalRecords": 230,
		"startIndex": 1,
		"pageNumber": 1,
		"endIndex": 100,
		"pageSize": 100
	},
	"items": [{
		"id": 10000000,
		"name": "Pepsi_Lineitem_Test_Inv",
		"status": {
			"id": 5,
			"name": "Draft"
		},
		"startDate": "2016-01-15T17:30:00",
		"endDate": "2016-01-16T19:30:00",
		"order": {
			"id": 10000001,
			"name": "Order_Pepsi"
		},
		"lineItemType": {
			"id": 2,
			"name": "Standard"
		},
		"goalUnit": {
			"id": 1,
			"name": "Absolute"
		},
		"goalPricing": {
			"id": 1,
			"name": "CPM"
		},
		"goal": 100000,
		"rate": 1,
		"currency": {
			"id": 1
		},
		"priority": 8,
		"account": {
			"id": 130917
		},
		"targetType": "ron"
	},
	{
		"id": 10000002,
		"name": "MG_LineItem_Sanity",
		"status": {
			"id": 9,
			"name": "Completed"
		},
		"startDate": "2016-01-15T12:00:00",
		"endDate": "2016-01-20T22:00:00",
		"order": {
			"id": 10000002,
			"name": "MG_Order_Sanity_Production"
		},
		"lineItemType": {
			"id": 2,
			"name": "Standard"
		},
		"goalUnit": {
			"id": 1,
			"name": "Absolute"
		},
		"goalPricing": {
			"id": 1,
			"name": "CPM"
		},
		"goal": 4500,
		"rate": 3,
		"currency": {
			"id": 1
		},
		"priority": 6,
		"account": {
			"id": 130917
		},
		"targetType": "ron"
	}]
}

Update Status

This API lets you update status of a set of line items.

This is a bulk line item status update API.
It validates the input line item ids for null / empty list and invalid ids as well as for invalid status.
Status Transition Rules are also used to validate whether the set of line items can be updated to requested status.

Request

URI	HTTP Method
https://api.pubmatic.com/v1/uas/lineitems/updateStatus/{statusId}	PATCH

Notes:

See Request Headers above for request header requirements.
See Request Body Parameters for parameters available to use in this request.

Sample Request URL

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

Sample Request JSON

[
    10003989
]

Sample Success Response

{
    "success": [
        10003989
    ],
    "errors": []
}

Error Codes for Line Item

Sr. No.	Error Codes	Description
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 the following fields for the Line Item API: id name order account goalUnit goalType goalPricing pace status target lineItemType user rate creativeRotation creative label isTest isHeld goal priority dealId minDailyGuaranteePercent startDate This error also occurs when the creative provided has a different advertiser than that of lineItem It also occurs if any target type is missed or any nested entity in target object have invalid id. Example, custom key id
2	PH_DUPLICATE_ENTITY	This error occurs when the value already exists in database for a unique identifier field. It can occur for following fields in case of Line Item API: Name
3	PH_PARAMETER_VALUE_TOO_LARGE	This error occurs when the input exceeds the permitted number of characters. It can occur for the following fields for the Line Item API: Name Description Insertion Order
4	PH_INVALID_ENTITY_START_DATE	Line item Start Date must be greater than/equal to Order Start Date.
5	PH_INVALID_ENTITY_END_DATE	Line item End Date must be greater than/equal to line item Start Date.
6	PH_UNSUPPORTED_STATUS	Unsupported value of a field is provided in request. line item does not support status -"Completed"
7	PH_ENTITY_RANGE_INCLUSIVE	This error occurs when the value provided is not in the required range. It can occur for the following fields for the Line Item API: Rate Goal frontLoadPercentage
8	PH_FRACTIONAL_VALUE_NT_SUPPORTED	Fractional value is not supported for goal and frontLoadPercentage.
9	PH_FIELD_NOT_SUPPORTED	frontLoadPercentage is not supported for pace other than fronLloaded.
10	PH_CAN_NOT_CHANGE_STATUS	Line item Status can not be changed for a given state. see status transition matrix above.
11	PH_INVALID_GOAL_UNIT	Invalid Goal Unit for a given line item Type and Goal Pricing.
12	PH_INVALID_GOAL_TYPE	Invalid Goal Type for a given line item Type and Goal Pricing.
13	PH_INVALID_GOAL_PRICING	Invalid Goal Pricing for a given line item Type.
14	PH_LI_CAN_NOT_DELETE	This error occurs when use attempt to delete a line Item but that is the only line item mapped to the order.
15	PH_ATTEMPT_TO_UPDATE_RESTRICTED_FIELD_IN_STATUS	This error occurs when a field is not editable in that status of line item. See editable field matrix above.
16	PH_LABEL_REPEATED_IN_HIERARCHY	This error occurs when you try to map an inherited label again to the entity.
17	PH_LABEL_EXCLUDED_IN_HIERARCHY	This error occurs when you try to exclude a label which is already excluded in the hierarchy above.
18	PH_CANNOT_CREATE_LINE_ITEM_FOR_ARCHIVED_ORDER	This error occurs when you try to create a line item fora an archived Order.
19	PH_UNSUPPORTED_VALUE	This error occurs when a user tries to enter an unsupported value for a particular field. It can occur for the following fields: status
20	PH_ATTEMPT_TO_UPDATE_SEALED_VALUE	This error occurs when a user tries to update a non-editable field. It can occur for following fields: dealId target currency
21	PH_ENTITY_NOT_BELONGS_TO_ACCOUNT	This error occurs when a user tries to create/update a line item with an Account different than that of its Order.
22	PH_UNSUPPORTED_END_DATE_FOR_ENTITY_TYPE	This error occurs when a user tries to enter an unsupported end date for a particular line item Type.
23	PH_UNSUPPORTED_FIELD_FOR_ENTITY_TYPE	This error occurs when a user tries to enter an unsupported field for a particular line item Type. It can occur for following fields: pace goal for a Wrapper line item frontLoadPercent for a Wrapper line item rate for a Wrapper line item goalType for a Wrapper line item goalPricing value as CPC for Wrapper line item goalUnit for Wrapper line item isTest for a Wrapper line item labels for a Wrapper line item frequencyCaps for a Wrapper line item
24	PH_LI_DEAL_ID_MISSING	This error occurs when a user does not provide Deal Id for a PMP type of line item.
25	PH_LI_FRONT_LOAD_MISSING	This error occurs when a user does not provide Front Load Percentage for Front Loaded pacing.
26.	PH_CANNOT_SET_HELD_START_DATE_EXPLICITLY	This error occurs if user passes heldStartDate while creating a line item. This error can also happen if user is trying to change heldStartDate while updating line item.
27.	PH_CANNOT_HELD_LINE_ITEM_FOR_NON_DRAFT_STATE_MSG	This error occurs if user tries to set isHeld = true for line item in any state other than DRAFT.
28.	PH_CANNOT_HELD_LINE_ITEM_FOR_NON_SPONSORED_STANDARD_MSG	This error occurs if user tries to set isHeld = true line item of any type other than standard or sponsorship.
29.	PH_CANNOT_SET_LINE_ITEM_TO_TEST	This error occurs when Test flag is set for Programmatic line Items.
30.	PH_ATTEMPT_TO_UPDATE_SEALED_VALUE_ACCOUNT_ID	This error occurs while trying to update the accountId of line Item.
31.	PH_CANNOT_MAP_LINE_ITEM_FOR_ARCHIVED_ORDER	This error occurs while creating / updating a lineItem for an archived order.
32.	PH_CANNOT_MAP_LINE_ITEM_FOR_COMPLETED_ORDER	This error occurs while creating / updating a lineItem for a completed order.
33.	PH_INVALID_START_DATE	This error occurs while setting null value for startDate
34.	PH_INVALID_ENTITY_END_DATE	This error occurs when endDate is not greater than startDate.
35.	PH_INVALID_END_DATE	This error occurs when lineItem endDate is null and endDate for lineItem's order is non-null or lineItem endDate is not less than lineItem's order endDate.
36.	PH_INVALID_FILTER_EXPRESSION	This error occurs when health is passed as a filter parameter in lineItem search request.
37.	PH_INVALID_SORT_KEY	This error occurs when health is passed as a sort parameter in lineItem search request
38.	PH_INPUT_SIZE_LIMIT_EXCEEDED	If more than 1000 line item ids are passed to update line item status API.
39.	PH_ERROR_INVALID_PARAMETER	When null status or null / empty line item ids are passed to line item status update API
40.	PH_UNSUPPORTED_VALUE	If invalid status Id is passed to line item status update API
41.	PH_AUTHORIZATION_ERROR	If user is not authorized to update status of line item passed in request to update line item status API
42.	PH_CAN_NOT_CHANGE_STATUS	Status Transition Rules are checked and if we are setting line item status to some not allowed value, then this error is thrown.

Unified Ad Server References

⇧ Top

Page tree

Line Item API (UAS)

Supported Operations

Request Headers and Response Body Parameters

Request Headers

Request Body Parameters

Status Transition Matrix

Status and Editable Fields Matrix

Operations and Samples

Create a Line Item

Request

Sample Request URL

Response

Retrieve the Details of a Line Item

Request

Sample Request URL

Response

Retrieve a List of Line Items

Request

Sample Request URL

Response

Update a Line Item

Request

Sample Request URL

Response

Update (Patch) a Line Item

Request

Sample Request URL

Sample Request JSON

Response

Delete a Line Item

Request

Sample Request URL

Response

Sample Response

Getting the Line Items Targeted to an adUnit

Request

AdUnit Targeted LineItems Dimensions

Sort Functionality

Getting the Line Items Targeted to adUnit

Sample Request URL

Response

Update Status

Request

Sample Request URL

Sample Request JSON

Sample Success Response

Error Codes for Line Item

Unified Ad Server References