Page tree



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

Methods                                      

Method Path

HTTP Method
Type

DescriptionLink to Definition
/buyerPOSTAdd a buyer to the PubMatic systemAdd a Buyer
/buyer/{id} GETRetrieve a specific buyer detail using a ID to be fetchedRetrieve Buyer Details
/buyerGET                            Retrieve list of buyers by specifying various filter criteriaRetrieve List of Buyers
/buyerPUTUpdate an existing buyer detailsUpdate a Buyer
/buyerDELETEDelete a buyer from the PubMatic systemDelete a Buyer



Add a Buyer


Overview

This API provides information about how to add a buyer in the PubMatic system with the specified input parameters.

Request

         

URI$URI_PREFIX/buyer
HTTP MethodPOST

Request Headers

               


Header NameTypeRequiredValidationsDescription
AuthorizationStringBearer ${access_token}Yes

The access token generated for authentication should be sent in place of ${access_token}.
For more information about access tokens, refer to Getting Started with PubMatic APIs.

Request Body

                             

Body ParameterTypeRequiredValidationsDescription
nameStringYes

1)Max length 250
2)Name should be unique across all buyers

Name of the Buyer
urlStringno URL of the buyer
deletedIntegerno 

Flag to delete Buyer
Default Value: 0

Sample Request JSON

POST $URI_PREFIX/buyer

{
"name" : "testBuyer" ,
"url" : "abc.com"
}
‍‍‍‍‍‍‍Response

Response Body

         

TypeDescription
buyer objectJSONresponse of newly created buyer

Sample Response JSON

        
{
"id" : 4110 ,
"name" : "testBuyer" ,
"url" : "abc.com" ,
"deleted" : 0 ,
"creationTime" : "2015-03-20 16:32:29"
}‍‍‍‍‍‍‍

Error Codes

Error Codes specific to this API method.

         

Error Code

Error Description

BA_01_001

Unable to create Buyer entity.

 

Sample Error Response


        [
        
{
errorCode: "BA_01_001"
error: "Unable to create Buyer entity."
}
]‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍


Retrieve Buyer Details

Overview

This API provides you information about retrieving a specific buyer details using the ID parameter.

Request

         

URI$URI_PREFIX/buyer/{id}
HTTP MethodGET

Request Headers

               

Header NameTypeRequiredValidationsDescription
AuthorizationStringBearer ${access_token}Yes

The access token generated for authentication should be sent in place of ${access_token}.
For more information about access tokens, refer to Getting Started with PubMatic APIs.


Path Parameters

               

Parameter NameTypeRequiredDescriptionSample Data
idLongYesBuyer ID for which details to be extracted 123

Sample Request

GET $URI_PREFIX/buyer/123

Response

Response Body

         

TypeDescription
JSON for record object  Details of Buyer entity


Sample Response JSON

        
{
"name" : "Didit" ,
"url" : "" ,
"deleted" : 0 ,
"creationTime" : "2011-04-14 21:51:04"
}‍‍‍‍‍‍

Error Codes

                 

Error CodeError Description
BA_01_005Unable to fetch entity for ID.
BA_01_007Buyer does not exist for ID.
SECURITY_401Unauthorized

Sample error response 

        
[
{
"errorCode" : "BA_01_007" ,
"error" : "Buyer does not exist for Id"
}
]‍‍‍‍‍‍



Retrieve a List of Buyers

Overview

This API provides information about how to retrieve the list of buyers using the specified filter parameters.   

Request

         

URI$URI_PREFIX/buyer
HTTP MethodGET

Request Headers

               

Header NameTypeValueRequiredDescription
AuthorizationStringBearer ${access_token}Yes

The access token generated for authentication should be sent in place of ${access_token}.
For more information about access tokens, refer to Getting Started with PubMatic APIs.

Request Query Parameters

                                    

Parameter NameTypeRequiredValidationsDescription
pageSizeintegerno 

The maximum number of rows to include in the response.
Default:100

pageNumberintegerno 

pageNumber to be fetched in case of multiple pages.
Default:1

filtersstringno

Must be from values mentioned below
in supported dimensions section.

Filters can be specified as a list of dimensions that restrict the data returned for your request.
More details can be found at Reporting and Listing API request.

sortstringno

Must be from values mentioned below
in supported dimensions section.

A list of comma-separated dimensions indicating the sorting order and sorting direction for the returned data.
More details can be found at Reporting and Listing API request.

 

See Generic Request for Reporting and Listing API for details on filter and sort parameters.
Note : notLike filter operator is not supported. 

Dimension Configurations

                                    

NameData TypeSummarySample filter dataSample sort data
idIntegerIndicates the id of the Buyer?filters=id eq 10

For ascending ?sort=id
For descending ?sort=-id

nameStringIndicates the name of Buyer?filters=name like testBuyer

For ascending ?sort=name
For descending ?sort=-name

urlStringIndicates the url of Buyer?filters=url like test

For ascending ?sort=description
For descending ?sort=-description

deletedIntegerIndicates whether the Buyer entity is deleted?filters=deleted eq 0

For ascending ?sort=name
For descending ?sort=-name

Sample Request

GET $URI_PREFIX/buyer?pageSize=25&pageNumber=1&filters=name like test

Response

Response Body

                

Response Body ParameterTypeDescription
 metaDataJSON Object This contains the metadata about the response generated.
itemsJSON Array of record objectThis gives the records formed as per your request.


Sample Response

        
{
"metaData" : {
"startIndex" : 1 ,
"totalRecords" : 1 ,
"endIndex" : 1
} ,
"items" : [
{
"id" : 1057 ,
"name" : "test" ,
"url" : "" ,
"deleted" : 0 ,
"creationTime" : "2012-07-27 22:27:39"
}
]
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Special handling for 'ALL' use case

If no filters are provided, all buyers will be listed.

HTTP response Status Codes

Here is the list of the HTTP statuses returned by API.

Error Codes

             

Error codeDescription
BA_01_004Unable to search entity
SECURITY_401Unauthorized


Sample Error Response

        
[
{
errorCode: "BA_01_004"error:
"Unable to search Buyer entity"
}
]‍‍‍‍‍‍


Update a Buyer

Overview

This API allows you to update an existing Buyer in the PubMatic system.

Re quest

         

URI$URI_PREFIX/buyer/{id}
HTTP MethodPUT

Request Headers

               

Header NameTypeRequiredValidationsDescription
AuthorizationStringBearer ${access_token}Yes

The access token generated for authentication should be sent in place of ${access_token}.
For more information about access tokens, refer to Getting Started with PubMatic APIs.

Path Parameters

               

Parameter Name  TypeRequiredDescriptionSample Data
idLongYesBuyer ID  for which details are to be updated123

Request Body

                         

Body ParameterTypeRequiredDescription
nameStringYesName of the Buyer
urlStringnoURL of the buyer
deletedIntegernoFlag to delete Buyer

Sample Request JSON

PUT $URI_PREFIX/buyer/
        4110
        
{
"name" : "testBuyer" ,
"url" : "abc.com"
}‍‍‍‍‍

Response

Response Body

         

TypeDescription
buyer objectJSONresponse of updated product

Sample  Response JSON

        {
        
"id" : 4110 ,
"name" : "testBuyer" ,
"url" : "abc.com" ,
"deleted" : 0 ,
"creationTime" : "2015-03-20 16:32:29"
}‍‍‍‍‍‍‍

Error Codes

             

Error CodeError Description
BA_01_002Unable to update buyer enity for ID
BA_01_007Buyer does not exist for ID


Sample error response

   {
        
"errorCode" : "BA_01_007" ,
"error" : "Buyer does not exist for Id"
}‍‍‍‍


Delete a Buyer

Overview

This API allows you to delete a buyer in the PubMatic system.

Request

         

URI$URI_PREFIX/buyer/
HTTP MethodDELETE

Request Headers

               

Header NameTypeRequiredValidations Description
AuthorizationStringBearer ${access_token}Yes

The access token generated for authentication should be sent in place of ${access_token}.
For more information about access tokens, refer to Getting Started with PubMatic APIs.

Request Query Parameters

             

Parameter NameTypeRequiredDescription
idLongYes ID of the Buyer to be deleted

Sample Request JSON:

DELETE $uri_prefix/buyer?id=123

Response

Response Body

         

TypeDescription
application jsonstatus of delete operation

 

Sample Response JSON

        {
        
"success" : " Buyer entity deleted successfully."
}
‍‍‍

Error Codes

             

Error CodeError Description
BA_01_007Buyer does not exist for ID
BA_01_003Unable to delete Buyer entity for ID

Sample Error Response

        [
        
{
"errorCode" : "BA_01_007" ,
"error" : "Buyer does not exist for id"
}
]‍‍‍‍‍‍

⇧ Top