MediaBuyer APIs - Buyers

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

Methods

 

                                     

Method Path
HTTP Method
Type
Description
Link to Definition
/buyerPOST
Add a buyer to the PubMatic system
Add a Buyer
/buyer/{id} 
GET
Retrieve a specific buyer detail using a ID to be fetched
Retrieve Buyer Details
/buyer
GET                            
Retrieve list of buyers by specifying various filter criteria
Retrieve List of Buyers
/buyer
PUT
Update an existing buyer details
Update a Buyer
/buyer
DELETE
Delete a buyer from the PubMatic system
Delete 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 Method
POST

Request Headers

               

 

Header Name
Type
Required
Validations
Description
Authorization
String
Bearer ${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 Parameter
Type
Required
Validations
Description
name
String
Yes
1)Max length 250
2)Name should be unique across all buyers
Name of the Buyer
url
String
no
 
URL of the buyer
deleted
Integer
no
 
Flag to delete Buyer
Default Value: 0

Sample Request JSON

POST $URI_PREFIX/buyer

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

Response Body

         

Type
Description
buyer objectJSON
response 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 Method
GET

Request Headers

               

Header Name
Type
Required
Validations
Description
Authorization
String
Bearer ${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
Type
Required
Description
Sample Data
id
Long
Yes
Buyer ID for which details to be extracted
 123

Sample Request

GET $URI_PREFIX/buyer/123

Response

Response Body

         

Type
Description
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 Code
Error Description
BA_01_005
Unable to fetch entity for ID.
BA_01_007
Buyer does not exist for ID.
SECURITY_401
Unauthorized

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 Method
GET

Request Headers

               

Header Name
Type
Value
Required
Description
Authorization
String
Bearer ${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 Name
Type
Required
Validations
Description
pageSize
integer
no
 
The maximum number of rows to include in the response.
Default:100
pageNumber
integer
no
 
pageNumber to be fetched in case of multiple pages.
Default:1
filters
string
no
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.
sort
string
no
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

                                    

Name
Data Type
Summary
Sample filter data
Sample sort data
id
Integer
Indicates the id of the Buyer
?filters=id eq 10
For ascending ?sort=id
For descending ?sort=-id
name
String
Indicates the name of Buyer
?filters=name like testBuyer
For ascending ?sort=name
For descending ?sort=-name
url
String
Indicates the url of Buyer
?filters=url like test
For ascending ?sort=description
For descending ?sort=-description
deleted
Integer
Indicates 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 Parameter
Type
Description
 metaData
JSON Object 
This contains the metadata about the response generated.
items
JSON Array of record object
This 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 code
Description
BA_01_004
Unable to search entity
SECURITY_401
Unauthorized

 

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.

Request

         

URI
$URI_PREFIX/buyer/{id}
HTTP Method
PUT

Request Headers

               

Header Name
Type
Required
Validations
Description
Authorization
String
Bearer ${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 
Type
Required
Description
Sample Data
id
Long
Yes
Buyer ID  for which details are to be updated
123

Request Body

                         

Body Parameter
Type
Required
Description
name
String
Yes
Name of the Buyer
url
String
no
URL of the buyer
deleted
Integer
no
Flag to delete Buyer

Sample Request JSON

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

Response

Response Body

         

Type
Description
buyer objectJSON
response 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 Code
Error Description
BA_01_002
Unable to update buyer enity for ID
BA_01_007
Buyer 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 Method
DELETE

Request Headers

               

Header Name
Type
Required
Validations
 Description
Authorization
String
Bearer ${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 Name
Type
Required
Description
id
Long
Yes
 ID of the Buyer to be deleted

Sample Request JSON:

DELETE $uri_prefix/buyer?id=123

Response

Response Body

         

Type
Description
application json
status of delete operation

 

Sample Response JSON

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

Error Codes

             

Error Code
Error Description
BA_01_007
Buyer does not exist for ID
BA_01_003
Unable to delete Buyer entity for ID

Sample Error Eesponse

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

Attachments

    Outcomes