Before using PubMatic APIs, first generate the API Token. For more information, refer to Getting Started with PubMatic APIs.
Use the following references for more information and instruction for Unified Ad Server APIs.
- Supported Operations for Services
- Common Request Query Parameters for Web Services
- Supported Operations for Filters
- HTTP Status Codes
- Unified Ad Server Specific Error Codes
|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.|
|dimensions||String||No||List of dimensions separated by a comma|
A list of comma-separated dimensions offered by respective web service.
|sort||String||No||List 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.
|filters||String||No||List of filters/conditions to perform condition search based on dimensions supported by Web service.|
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.
|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 you may add * at start and end of search keyword
name like test
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.|
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.|