MediaBuyer APIs - DSPs

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

Methods

 

                                     

Method Path
HTTP Method
Type
Description
Link to Definition
 /dsp
POST
Add a DSP in the PubMatic systemAdd a DSP
/dsp/{id}
GET
Retrieve a DSP details using a specific ID
Retrieve DSP Details
/dsp
GET
Search the desired DSP entity
Retrieve List of DSPs
 /dsp                    
PUT                                  
Update an existing  DSP            
Update a DSP
 /dsp
DELETEDelete 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 Code
Error Description
BA_01_001
Unable to create DSP entity.
BA_01_006
DSP 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 Method
GET

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.

 

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

         

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

Sample error response

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

 

Retrieve List of DSPs

Overview

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

Request

         

URI
$URI_PREFIX/dsp
HTTP Method
GET

Request Headers

               

Header Name
Type
Value
Required
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 Query Parameters

                               

Parameter Name
Type
Required
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
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
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 DSP
?filters=id eq 10
For ascending ?sort=id
For descending ?sort=-id
name
String
Indicates the name of DSP
?filters=name like testDSP
For ascending ?sort=name
For descending ?sort=-name
deleted
Integer
Indicates 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 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": 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 code
Description
BA_01_004
Unable to search entity
SECURITY_401
Unauthorized

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

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.

Path Parameters

               

Parameter Name
Type
Required
Description
Sample Data
id
Long
Yes
DSP ID  for which details are to be updated
123

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


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

         

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

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 Query Parameters

             

Parameter Name
Type
Required
Description
id
Long
Yes
 ID of the DSP to be deleted

Sample Request JSON

DELETE $uri_prefix/dsp?id=123

Response

Response Body

         

Type
Description
application json
status of delete operation

Sample Response JSON


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

Error Codes

             

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

Sample error response


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

Attachments

    Outcomes