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
 /dspPOSTAdd a DSP in the PubMatic systemAdd a DSP
/dsp/{id}GETRetrieve a DSP details using a specific IDRetrieve DSP Details
/dspGETSearch the desired DSP entityRetrieve List of DSPs
 /dsp                    PUT                                  Update an existing  DSP            Update a DSP
 /dspDELETEDelete a DSP from the PubMatic systemDelete a DSP


Add a DSP

Overview

This API helps provides you information about how to create a single DSP with specified input parameters.


Request

         

URI

$URI_PREFIX/dsp

HTTP Method

POST

Request Headers

               

Header Name

Type

Required

Validations

Description

Authorization

String

Bearer ${access_token}

Yes

Need to send the access token generating for authentication at the place of ${access_token}.

For more information about access tokens, refer to Getting Started with PubMatic APIs.


Request Body

                                                                                                 

Body Parameter

Type

Required

Default Value

Validations

Description

name

String

Yes

 

1)Max length 250

2)Name should be unique across all DSPs

Name of the DSP

notes

String

no

  

Notes about DSP

deleted

Integer

no

0

 

Flag to delete DSP

entityType

Integer

no

1

 

Entity Type

industryType

String

no

  

Industry Type

tierId

Integer

no

3

 

Tier Id

accountManagerId

Integer

yes

1

 

Account Manager Id

isCoppaCompliant

Integer

yes

0

 

Is Coppa Compliant flag

supportsFirstPrice

Integer

no

0

 

Supports First Price flag

filterBotInventory

Integer

no

0

  

currencyId

Integer

no

1

 

ID of currency

Sample Request JSON

        
POST $URI_PREFIX/dsp

{
"entityType" : 2 ,
"name" : "New DSP12" ,
"notes" : "" ,
"industryType" : "" ,
"tierId" : 3 ,
"accountManagerId" : 1 ,
"deleted" : 0 ,
"isCoppaCompliant" : 0 ,
"supportsFirstPrice" : 0 ,
"filterBotInventory" : 0 ,
"currencyId" : 1
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Response Body

         

Type

Description

DSP objectJSON

response of newly created DSP

Sample Response JSON

        
{
"id" : 582 ,
"entityType" : 2 ,
"name" : "New DSP12" ,
"notes" : "" ,
"industryType" : "" ,
"tierId" : 3 ,
"accountManagerId" : 1 ,
"deleted" : 0 ,
"isCoppaCompliant" : 0 ,
"supportsFirstPrice" : 0 ,
"filterBotInventory" : 0 ,
"currencyId" : 1
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Error Codes

             

Error CodeError Description
BA_01_001Unable to create DSP entity.
BA_01_006DSP already exists for name


Sample Error Response

        [
        
{
"errorCode" : "BA_01_006" ,
"error" : "DSP already exists for name testDspMyTst5."
}
]
‍‍‍‍‍‍


Retrieve DSP Details

Overview

This API helps you in retrieving the DSP details using a specified ID parameter.

Request

         

URI$URI_PREFIX/dsp/{id}
HTTP MethodGET

Request Headers

               

Header NameTypeRequiredValidations Description
AuthorizationStringBearer ${access_token}Yes

Need to send the access token generating for authentication at the 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

DSP Id for which details to be extracted

 123

Sample Request

        
GET $URI_PREFIX/dsp/123

Response Body

         

TypeDescription
JSON for record object  Details of DSP entity

Sample Response JSON

        
{
"entityType" : 1 ,
"name" : "xebia_demand_partner" ,
"notes" : "" ,
"industryType" : "" ,
"tierId" : 2 ,
"accountManagerId" : 1 ,
"deleted" : 0 ,
"creationTime" : "2015-01-06 12:12:11" ,
"modificationTime" : "2015-01-06 12:12:11" ,
"isCoppaCompliant" : 1 ,
"supportsFirstPrice" : 0 ,
"filterBotInventory" : 0 ,
"currencyId" : 1
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Error Codes

                 

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

Sample error response

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


Retrieve List of DSPs

O verview

This API provides information about how to create a list of DSPs using various filter parameters.

Request

         

URI$URI_PREFIX/dsp
HTTP MethodGET

Request Headers

               

Header NameTypeValueRequiredDescription
AuthorizationStringBearer ${access_token}Yes

Need to send the access token generating for authentication at the place of ${access_token}.

For more information about access tokens, refer to Getting Started with PubMatic APIs.


Request Query Parameters

                               

Parameter NameTypeRequiredDescription
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

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

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 DSP?filters=id eq 10

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

nameStringIndicates the name of DSP?filters=name like testDSP

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

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

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

Sample Request

GET $URI_PREFIX/dsp?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" : 491 ,
"entityType" : 1 ,
"name" : "Test" ,
"notes" : "" ,
"industryType" : "" ,
"tierId" : 3 ,
"accountManagerId" : 1 ,
"deleted" : 0 ,
"creationTime" : "2013-08-27 00:41:08" ,
"modificationTime" : "2013-08-27 00:41:08" ,
"isCoppaCompliant" : 0 ,
"supportsFirstPrice" : 0 ,
"filterBotInventory" : 0 ,
"currencyId" : 1
}
]
} ‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Special handling for 'ALL' use case

 If no filters are provided, all DSPs 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 DSP entity"
}
]‍‍‍‍‍‍


Update a DSP

Overview

This API provides information about updating an existing DSP details.

Request

         

URI$URI_PREFIX/dsp/{id}
HTTP MethodPUT

Request Headers

               

Header NameTypeRequiredValidationsDescription
AuthorizationStringBearer ${access_token}Yes

Need to send the access token generating for authentication at the place of ${access_token}.

For more information about access tokens, refer to Getting Started with PubMatic APIs.

Path Parameters

               

Parameter NameTypeRequiredDescriptionSample Data
idLongYesDSP ID  for which details are to be updated123

Request Body

                                                                                                 

Body ParameterTypeRequiredDefault ValueValidationsDescription
nameStringYes 

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

Name of the DSP
notesStringno  Notes about DSP
deletedIntegerno0 Flag to delete DSP
entityTypeIntegerno1 Entity Type

industryType
  

Stringno  Industry Type
tierIdIntegerno3 Tier ID
accountManagerIdIntegeryes1 Account Manager ID
isCoppaCompliantIntegeryes0 Is Coppa Compliant flag
supportsFirstPriceIntegerno0 Supports First Price flag
filterBotInventoryIntegerno0  
currencyIdIntegerno1 ID of currency

Sample Request JSON

        
PUT $URI_PREFIX/dsp/ 9

{
"entityType" : 1 ,
"name" : "Video Egg23" ,
"notes" : "" ,
"industryType" : "" ,
"tierId" : 2 ,
"accountManagerId" : 1 ,
"deleted" : 0 ,
"isCoppaCompliant" : 0 ,
"supportsFirstPrice" : 0 ,
"filterBotInventory" : 0 ,
"currencyId" : 1
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Response

Response Body

         

TypeDescription
DSP objectJSONresponse of updated product

Sample Response JSON

        
{
"entityType" : 1 ,
"name" : "Video Egg23" ,
"notes" : "" ,
"industryType" : "" ,
"tierId" : 2 ,
"accountManagerId" : 1 ,
"deleted" : 0 ,
"creationTime" : "2008-10-30 04:18:12" ,
"modificationTime" : "2015-03-23 14:03:43" ,
"isCoppaCompliant" : 0 ,
"supportsFirstPrice" : 0 ,
"filterBotInventory" : 0 ,
"currencyId" : 1
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Error Codes

             

Error CodeError Description
BA_01_002Unable to update DSP enity for ID
BA_01_007DSP does not exist for ID

Sample error response

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


Delete a DSP

Overview

This API allows you to delete a DSP in PubMatic system.

Request

         

URI$URI_PREFIX/dsp/
HTTP MethodDELETE

Request Headers

               

Header NameTypeRequiredValidationsDescription
AuthorizationStringBearer ${access_token}Yes

Need to send the access token generating for authentication at the 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 DSP to be deleted

Sample Request JSON

DELETE $uri_prefix/dsp?id=123

Response

Response Body

         

TypeDescription
application jsonstatus of delete operation

Sample Response JSON

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

Error Codes

             

Error CodeError Description
BA_01_007DSP does not exist for ID
BA_01_003Unable to delete DSP entity for ID

Sample error response

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