Unified Ad Server (UAS) References

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

Use the following references for more information and instruction 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
dimensionsStringNoList of dimensions separated by a comma

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.
sortStringNoList of dimensions separated by comma sorted by the criteria specified.

A list of comma-separated dimensions to sort the 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 sort key not found in the requested query, you will receive a "Bad Request" response along with the error code, INVALID_SORT_KEY.

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

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.
    e.g. &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. e.g. &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 Operations for Filters                                                 

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 you may 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.

Attachments

    Outcomes