See the following sections for more information, instructions, and references for Unified Ad Server APIs:
Supported Operations for Services
|Operation||HTTP Method||Post Body||Comments|
|Create||POST||JSON string as per API protocol||Used to create a record in the system. Only supported for specific services where applicable. Please check the respective API pages for more details.|
|Update||PUT||JSON 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.
|Update||PATCH||JSON string as per API protocol||Used 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 Search||GET||N/A||Used 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.
|Archive||DELETE||N/A||Used 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
List of dimensions separated by a comma.
See Supported Dimensions below for details.
A list of comma-separated dimensions offered by respective web service.
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.
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
|pageNumber||Integer||No||Page 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.
|pageSize||Integer||No||Number 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.
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.
|account||Integer||Yes||Account of the Publisher|
|name||String||Yes||Line Item Name|
|order||Integer||Yes||Order identifier for which a requested record should map.|
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:
|endDate||String||No||End date and time for a requested record.|
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.
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 ).
Specifies the priority of a line item, relative to competing line items, in cases when inventory is over committed. Priorities can be applied to
|status||Integer||Yes||Status of the Line Item.|
You can retrieve the list of status using Status API
Following status are supported for a Line Item -
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.
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
Describes how the line item is priced.
To retrieve the list of supported pricing model by Phoenix you can use Goal Pricing API
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).
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
|rate||Double upto 2 places of decimal||Yes||Represents the average rate ( ecpm) of the selected line item.|
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.
|adUnitId||Integer||No||It is the adUnitId against which the lineitem is targeted.|
|targetType||String||No||This specifies the type with which lineItem is targeted against the adUnit. It can have values viz. direct, inherited, RON.|
|timeZone||Object||No||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 operates on a single dimension. Sorting by multiple dimensions is not supported by this API. Currently, custom sort functionality works only with object types:
The following attributes support sort functionality:
|Operator||Description||Supported Data Type||Example|
|eq||equal to||All data types|
id eq 1234
id eq null
|noteq||Not equal to||All data types|
id noteq 1234
id noteq null
id gt 1234
|gteq||Greater than equal to||Numeric|
id gteq 1234
id lt 1234
|lteq||Less than equal to||Numeric|
id lteq 1234
For similar search, add * at start and end of search keyword
name like test
HTTP Status Codes
Below are the common HTTP status codes sent in REST API response by PubMatic API platform:
|200||OK||Indicates that the request has been successfully processed; check contents of body.|
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:
|401||Unauthorized||Indicates that there is authentication or authorization failure; check the response body for specific details.|
|403||Forbidden||Indicates that you are not subscribed to this feature of the Platform.|
|404||Not Found||Indicates that sever do not have this resource.|
|405||Method Not Allowed||Indicates that the method specified in the request is not allowed for the resource identified by the Request-URI.|
|413||Request Entity Too Large||Indicates 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.|
|415||Unsupported Media Type||Indicates 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.|
|500||Internal Server Error||Indicates 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.
HTTP Status Code
Checks if requested dimension is supported by the API
400 - Bad Request
Requested dimension(s) is not supported.
|sort||Check if sort key present in dimension list in the request||INVALID_SORT_KEY||400 - Bad Request||Sort key is not found in requested dimensions.|
Checks if filter expression is parsed correctly
400 - Bad Request
Filter expression invalid. Not able to parse filter expression.
|filters||Check if filter key is available in supported dimension by respective service.||INVALID_FILTER_KEY||400 - Bad Request||Invalid filter key(s). Filter can be applied only on valid dimensions supported by service.|
|filters||Check 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 Type||INVALID_FILTER_VALUE||400 - Bad Request||Data type mismatch in filter expression.|