Page tree


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

 

Overview

Infrastructure APIs provide common functionality that is needed across multiple products; for example uploading entities in bulk, bulk downloads, etc.


Infrastructure API for bulk upload is essentially a delegating API, which does some groundwork and then delegates to an actual product specific API. The actual work is done by a more product specific API.


The Bulk Upload end points provided by the Infrastructure API are currently being used (via UI) for uploading publisher sites, publisher ad tags, channel partner domains, placements, F-cap and i-cap settings, publisher blocklist, channel partner domain deletion, campaign blocklist and whitelist etc.


The Bulk upload API operation itself is asynchronous (meaning you don't see results immediately). The following four APIs have been provided to upload and check status:


Methods

                                 

Method PathHTTP Method TypeDescriptionLink to Definition
/infrastructure/bulkoperationsPOST

This API gives the functionality of providing the bulk operations on APIs using supported multi-part request formats.


This method submits the file to the uploader process. (At this point processing has not completed.)

Bulk Uploads

/infrastructure/bulkOperations/GET

Get the list of bulk operations as per the criteria given in request.


This API can be used to check the status for a job that was submitted earlier.

Get all Bulk Uploads
/infrastructure/bulkOperations/{id}/failedRecordsGET

Once a job completes following APIs can be used to fetch records that went through and records which did not because of validation errors.


This method gets the file of failed records.

Get failed records
/infrastructure/bulkOperations/{id}/successfulRecordsGET

Once a job completes following APIs can be used to fetch records that went through and records which did not because of validation errors.


This method gets the file of successful records.

Get successful records



Bulk Uploads

Overview

End point for starting a bulk operation. After successful creation of a bulk operation, it will start processing the payload file asynchronously and will perform the actual API operations.


Once the basic file validations (empty file, file size, CSV header match) are done, the uploaded file is stored in the database and the Batch Id is generated for the same. This Batch Id can be used later to download successful and failed entries after the completion of entire process. Request is then sent to specific APIs to perform the operations as per input resource url.

Request

         

URI${uri_prefix}/infrastructure/bulkOperations
HTTP MethodPOST

Request Headers

                 

Header NameTypeValueRequiredDescription
Content-Typeapplication/jsonMust be MULTIPART_FORM_DATAYes


Request Query Parameters

                                                                                                                                                                                  

Body ParameterTypeRequiredValidationsDescription
PubTokenStringYes

${access_token}

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


Sample Request

Bulk Domain Upload

http://localhost:8080/infrastructure/bulkOperations/[FileID]/successfulRecords?PubToken=xxxxx 


Response

Sample Response

The operation response with a CSV File. See attached example, "Sample_DomainsBulkUpload.csv.zip".



Get All Bulk Uploads

Overview


End point for retrieving all the upload details done for a publisher.

Request

         

URI${uri_prefix}/infrastructure/bulkOperations
HTTP MethodGET

Request Headers

                 

Header NameTypeValueRequiredDescription
Content-Typeapplication/json
Yes


Request Query Parameters

                                                                                                                                                                                  

Body ParameterTypeRequiredValidationsDescription
PubTokenStringYes

${access_token}

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

entityIdLongYes


Publisher Id for which domains have been uploaded.
urlStringYes

String to describe the type of bulk upload for which details have to be retrieved.
e.g., In case of domain upload value of uri will be "topLevelAd Container"

pageNumberIntegerNo
The starting count of records to be retrieved
pageSizeIntegerNo
Total number of records to be retrieved
sortStringNo
Retrieval order of the records


Sample Request

http://localhost:9090/infrastructure/bulkOperations?entityId=1234&PubToken=xxxxxxxxx&uri=topLevelAdContainer&dimensions=… 

Response

Sample Response JSON

{
   "metaData":{
      "startIndex":1,
      "totalRecords":1,
      "endIndex":10
   },
   "items":[
      {
         "id":123,
         "userId":123,
         "numberOfSuccessRecords":1,
         "numberOfErrorRecords":0,
         "fileName":"Uploaded_file.csv",
         "status":1,
         "creationTime":"2017-02-24 11:34:39",
         "comments":"",
         "bulkOperationsStatus":"Success",
         "userEmailId":"test@pubmatic.com",
         "modificationTime":"2017-02-24 11:35:43"
      }
   ]
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍


Response Body

ParameterTypeDescription
metaDataObjectContains meta information such as start index, end index and total records.
itemsListContains a list of bulk operation objects. The object contains file/batch id, user details (id ad email), number of successful and failed records, file name, bulk operation status (0=In Progress, 1=Success, 2=Failed) of the complete processing.


Get Failed Records

Overview

End point for retrieving all the failed records for input Batch/File Id. (This batch/file id is generated after the file is uploaded successfully during the bulk operation).

Request

         


URI${uri_prefix}/infrastructure/bulkOperations/{id}/failedRecords
HTTP MethodGET


Request Query Parameters

                                                                                                                                                                                  

Body ParameterTypeRequiredValidationsDescription
PubTokenStringYes

${access_token}

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


Sample Request


http://localhost:8080/infrastructure/bulkOperations/23542/failedRecords?PubToken=xxxxx 


Response

Sample Response

The operation response with a file containing failed records in CSV format. See attached example, "FailedEntries.csv.zip".


Get Successful Records

Overview

End point for retrieving all the successful records for input Batch/File Id(This batch/file id is generated after the file is uploaded successfully during the bulk operation).

Request

         

URI${uri_prefix}/infrastructure/bulkOperations/{id}/successfulRecords
HTTP MethodGET

Request Query Parameters

                                                                                                                                                                                  

Body ParameterTypeRequiredValidationsDescription
PubTokenStringYes

${access_token}

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


Sample Request

http://localhost:8080/infrastructure/bulkOperations/23542/successfulRecords?PubToken=xxxxx 


Response

Sample Response

The operation response with a file containing failed records in CSV format. See attached example, "SuccessfulEntries.csv.zip".