Unified Ad Server (UAS) References

Document created by pubmatic-archivist on Mar 27, 2017Last modified by david.simerly on Sep 5, 2018
Version 17Show Document
  • View in full screen mode
Before using PubMatic APIs, first generate the API Token. For more information, see Getting Started with PubMatic APIs.

See the following sections for more information, instructions, and references for Unified Ad Server APIs:

 

Supported Operations for Services

OperationHTTP MethodPost BodyComments
CreatePOSTJSON string as per API protocolUsed to create a record in the system. Only supported for specific services where applicable. Please check the respective API pages for more details.
UpdatePUTJSON string as per API protocol

Used to update the records for given identifier. Only supported for specific services where applicable. Please check the respective API page for more details.

 

While performing an update operation using PUT, if any parameter missing in JSON string that are optional for specified web service, it will update with with default value silently.

Important Note: You must provide the complete JSON object with the parameter and new value which you would like to change.

  

If you would like to provide only parameter(s) with new value those want to update, use the PATCH method.

UpdatePATCHJSON string as per API protocolUsed to update the records for the given identifier with specific parameter(s). Only supported for service where applicable. Please check respective API page for more details.
Retrieve/Generic SearchGETN/AUsed to fetch all the records for given entity associated with your account or a record having specific id.
You can also use set of dimensions and filters to fetch conditional records from the system.
ArchiveDELETEN/AUsed to archive a particular record for a given identifier. This is only supported for specific services where applicable. Please check respective API page for more details.

 

Common Request Query Parameters for Web Services

Parameter NameTypeRequiredValidationsDescription
dimensionsStringNo

List of dimensions separated by a comma.

See Supported Dimensions below for details.

A list of comma-separated dimensions offered by respective web service.
If dimensions is not present in the query, the API will respond against all the dimensions supported by web service.
Important note:

  • Empty spaces are not allowed within the dimension list.
  • The parameter names in dimension, sort and filters are case sensitive.
sortStringNo

List of dimensions separated by comma sorted by the criteria specified.

See Sort Functionality below for details.

A list of comma-separated dimensions to sort the returned records either in ascending or descending order.

 

You can sort in descending order by using a minus sign prefix on the requested sort field.

 

If your query is missing a sort key, the query returns a, "Bad Request" response with the error code, INVALID_SORT_KEY.

filtersStringNo

List of filters/conditions to perform condition search based on dimensions supported by Web service.

See Filter Operators below for details.

  

A single filter uses the form: name operator value
In the above syntax:

  • name = dimension name on which you have to apply the filter
  • operator = defines the type of filter match to use. Find more details on supported filter operations
  • value = states the values to be included in or excluded from the results.

Filter Types:

  • AND: Filter conditions passed in the request as multiple values for filters parameter use AND.
    For example: &filters=<dim1> EQ <value1>&filters=<dim2> EQ <value2> is interpreted is interpreted as (dim1= value1 AND dim2= value2).
  • OR: Comma( , ) separated filter conditions in the value of filters parameter use OR. For example: &filters=<dim1> EQ <value1>,<dim2> EQ <value2> is interpreted as (dim1= value1 OR dim2= value2).

Important notes:

  • There should be space between name, operator and value.
  • Operator are not case sensitive. For example, noteq and NOTEQ are considered the same.
pageNumberIntegerNoPage number to get data for a particular page. Default value is 1.Page number to get data for particular page. Default value is 1.
Providing zero or negative number will result in setting default value of 1.
pageSizeIntegerNoNumber of records to fetch on specific pageNumber. If pageSize is not specified, the default value will be 100.

Indicates the number of records returned from the API on specific page.
Providing zero or negative number would result in setting default value of 100.

Important Note: If pageNumber and pageSize parameters are not found in the request then pageNumber will be set as the default value of 1 and pageSize will be equal to totalRecords.

 

Supported Dimensions

Parameter Name
Type
Required
Validations
Description
accountIntegerYes
  1. Account of publisher for which this Line item is created
Account of the Publisher
nameStringYes
  1. Name should be unique for your account.
  2. Name can be of maximum 255 characters consisting of letters, numbers, dashes, hyphens, periods, asterisks, and colons.
Line Item Name
orderIntegerYes
  1. Should be a valid, non-negative identifier for order.
Order identifier for which a requested record should map.
startDateStringYes
  1. Date and Time within Order start and end date and time.
  2. Date and Time must be in  yyyy-MM-dd'T'HH:mm:ss 
    For example, 2016-06-01T00:00:00

Start date and time of the requested record will become active; for example, when a line item will begin delivering. You can also pass "now" rather than an explicit date to request ASAP.  The API sets dates based on the following conditions:

  1. If order start date is in the past, the query will return requested records based on the current date/time in the order's time zone.
  2. If order start date is in the future, the query returns requested records based on the order's start date/time in the order 's time zone.

For example:

{
    "startDate":"now"
}
endDateStringNo
  1. End date/time for the requested record; for example, the end date/time a line item is expected to complete.
  2. End date and Time should be greater than start date and time.
  3. End date should be less than or equal to order end date and time.
  4. Date and Time must be in  yyyy-MM-dd'T'HH:mm:ss 
    For example, 2016-06-01T00:00:00
  5. If you would like to set line item which will run for indefinitely please do not pass this parameter.                           
End date and time for a requested record.
lineItemTypeIntegerNo
  1. Should be valid and exists in the system.
  2. 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. Following table summarized the rules.

Line Item Type
Goal Pricing
Goal Type
Goal Unit
Description
SponsorshipCPM / CPCImpressionsPercentage% of total impressions (0 to 100%)
StandardCPMImpressionsAbsoluteNumber of impressions
 CPCClicks AbsoluteNumber of clicks
HouseCPM / CPCImpressionsPercentage% of remaining impressions
PMPCPMImpressionsPercentage% of remaining impressions
RTBCPMImpressionsPercentage% of remaining impressions
WrapperCPMNot ApplicableNot ApplicableGoal type and goal unit are not applicable

Note:For PMP type of line item, default priority is set to 5, but it could have priority in range of ( 5-16 ) while, for RTB type of line item, default priority is set to 8 ,but it could have priority in range of ( 8-16 ).

priorityIntegerNo
  1. Priority for the line item.
  2. You can assigned the priority depends on line item type. following table summarized the valid prioritize for respective line items.

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

Line Item Type
Priority Range
Sponsorship1 - 4
Standard5 - 14
House13 - 16
Open Exchange8-16
PMP5-16
Wrapper8-16
statusIntegerYes
  1. Status should be valid and exists.
  2. Default is "Draft" for newly created line item.


Status of the Line Item.

You can retrieve the list of status using Status API

Following status are supported for a Line Item -

Id
Name
Id
Name
1Active2Inactive
4

Archived

5Draft
7Delivering8Paused
9Completed11In Review
12Rejected 13 Failed

The system makes the Line Item active once user maps the creatives to that line item. This is valid only 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", "Failed" 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", "Failed" and "Rejected" to apply filters and for searching Line item having this status.

targetIntegerNo
  1. It 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 given line item. Please refer to Phoenix API#LineItemTargetingServices

goalPricingIntegerYes
  1. It should be valid and non negative.

Describes how the line item is priced.

To retrieve the list of supported pricing model by Phoenix you can use Goal Pricing API

Pricing Model
Description
1CPM: Cost per thousand impressions
2

CPC: Cost per click.

goalIntegerYes
  1. Valid, non negative and should be greater than zero.

Defines the total goal of the line item. For guaranteed line items goal must be achieved. For non guaranteed achieving goals are not guaranteed however it is guaranteed to not exceed the goal.

Goal is closely tied to Pricing model and UI must ensure that. Example: If CPC pricing model is chosen goal is a whole number indicating number of clicks. If Share of Voice is chosen then goal is a whole number indicating percentage (1 - 100).

goalUnitIntegerYes
  1. Should be valid and exists.

Goal Unit. It could be either Absolute Number or in form percentage for the goal.

To retrieve the list of supported Goal Units by Phoenix you can use Goal Unit API

Goal Unit
Description
1Absolute
2Percentage
rateDouble upto 2 places of decimalYes
  1. Must be greater than or equal to 0 and less than/equal to 999999999.00
Represents the average rate ( ecpm) of the selected line item.
currencyCurrency ObjectNo
  1. Read Only
  2. 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. 

 

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.

adUnitIdIntegerNo
  1. Read only
  2. Not expected in the request
It is the adUnitId against which the lineitem is targeted.
targetTypeStringNo
  1. Should be a valid value.
This specifies the type with which lineItem is targeted against the adUnit. It can have values viz. direct, inherited, RON.
timeZoneObjectNo
  1. Read Only
  2. Not expected in the request and will always be returned by the API.
It specifies the timeZone in which lineItem will run. The timeZone is extracted from the order and if not found, extracted from the account.

 

Sort Functionality

Sort operates on a single dimension. Sorting by multiple dimensions is not supported by this API. Currently, custom sort functionality works only with object types:

 

  • primitives
  • wrappers
  • Date
  • String
  • PubMaticEntity

 

The following attributes support sort functionality:

 

  • id
  • name
  • startDate
  • endDate
  • lineItemType
  • priority
  • status

 

Filter Operators

OperatorDescriptionSupported Data TypeExample
eqequal toAll data types

id eq 1234

id eq null

noteqNot equal toAll data types

id noteq 1234

id noteq null

gtGreater thanNumeric

id gt 1234

gteqGreater than equal toNumeric

id gteq 1234

ltLess thanNumeric

id lt 1234

lteqLess than equal toNumeric

id lteq 1234

like

Like

For similar search, add * at start and end of search keyword

String

name like test

 

 

HTTP Status Codes

Below are the common HTTP status codes sent in REST API response by PubMatic API platform:

StatusTextDescription
200OKIndicates that the request has been successfully processed; check contents of body.
400Bad Request

Indicates that there is some validation failure; check the response body for error details.

In this case, an error message is displayed which includes following error conditions:

  • Invalid parameter value
  • Parameter value out of bound
401UnauthorizedIndicates that there is authentication or authorization failure; check the response body for specific details.
403ForbiddenIndicates that you are not subscribed to this feature of the Platform.
404Not FoundIndicates that sever do not have this resource.
405Method Not AllowedIndicates that the method specified in the request is not allowed for the resource identified by the Request-URI.
413Request Entity Too LargeIndicates that this request is used when the request content exceeds the size limit.  This may be the number of records or the actual content size.
415Unsupported Media TypeIndicates that server is refusing to service the request because the entity of the request is in a format not supported by the requested resource for the requested method.
500Internal Server ErrorIndicates that there is problem in the PubMatic API Platform; need to convey this to PubMatic api support team for further details.

 

Unified Ad Server Specific Error Codes

The Unified Ad Server Web Services will send the following error codes in addition to the standard error codes. These are common to Retrieve and Generic search operations.

Field

Validations

Error Code

HTTP Status Code

Error Description

dimensions

Checks if requested dimension is supported by the API

INVALID_DIMENSION

400 - Bad Request

Requested dimension(s) is not supported.

sortCheck if sort key present in dimension list in the requestINVALID_SORT_KEY400 - Bad RequestSort key is not found in requested dimensions.

filters

Checks if filter expression is parsed correctly

INVALID_FILTER_EXPRESSION

400 - Bad Request

Filter expression invalid. Not able to parse filter expression.

filtersCheck if filter key is available in supported dimension by respective service.INVALID_FILTER_KEY400 - Bad RequestInvalid filter key(s). Filter can be applied only on valid dimensions supported by service.
filtersCheck if filter expression is valid i.e. "gt" can not be applied on string data type or "like" can not be apply on Numeric data TypeINVALID_FILTER_VALUE400 - Bad RequestData type mismatch in filter expression.

 

Unified Ad Server References

 

⇧ Top

Attachments

    Outcomes