Webhook Data pull 

Below document highlights the webhook registration and data pull method to pull large data set from PubMatic.

Data Pull Flow Diagram

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

Webhook Registration

Once you have your access token, a one-time setup is required before data pull requests can be submitted. If this step is skipped, PubMatic will send an email notification of data availability reports to the user associated with the pubtoken instead of the endpoint.

If a change is required in the endpoint, this step can be repeated with a different endpoint URL, as explained below.

{id} = the publisher ID in PubMatic.
DescriptionMethod PathHTTP Method TypeBody Content
Add a new endpoint to the list of existing endpoints

/v1 /analytics/ptp/publisher/notification/update/{id}



Where, url = A new endpoint where PubMatic will send the notification for data availability in addition to the original list.

Remove given endpoint from the list/v1 /analytics/ptp/publisher/notification/update/{id}DELETE


Where, url = Remove given endpoint from a list of existing endpoints.

Note: If empty string is passed, PubMatic will not do anything.   

Data Pull Flow

1. Submit data pull requests or schedule reports

The publisher submits data pull requests with GET method to the endpoint provided by PubMatic. Alternatively, the publisher can schedule reports for a specific frequency.

DescriptionMethod PathHTTP Method TypeRequest Query ParametersExpected Response
Submit data pull requests to PubMatic/v1/analytics/ptp/publisher/{id}GET

dateUnit=Supported time units. Example: date

dimensions=list of supported dimensions separated by comma. Example: siteId,countryId,date,keyValue

metrics=list of supported metrics separated by comma. Example: revenue,paidImpressions,totalRequests

fromDate=Start date of data retrieval. Example: 2018-01-01

toDate=End date of data retrieval. Example: 2018-01-02


Note: Publisher must store above "queryId" to pull data for this request and to check the status of the data availability/report status. If dateUnit, dimensions, metrics or date ranges are not supported or invalid, PubMatic will return error.



2. Obtain the status of the request

Get the status of whether the report query was submitted successfully or whether to abort the data pull request.

DescriptionMethod PathHTTP Method TypeRequest Query ParametersExpected Response
Status of the report query is successful/v1/analytics/ptp/publisher/status/{id}GET

queryId=Returned query id in step 1 (above). Example: 1234abc

{"queryId":"1234abc", "status":"COMPLETED"}

Possible statuses:

COMPLETED: Data is available to be pulled.

JOB_SUCCEEDED: Job completed the data pull.

JOB_RUNNING: Job to prepare data is running.

FAILED: Data pull failed.

ABORTED: Data pull request aborted.

Abort the data pull request



queryId=Returned query id from step 1 (above).

Example: 1234abc

200 ok

3. PubMatic sends metadata for the data pull in a webhook notification

Once data is available to be pulled, PubMatic sends a webhook notification; a simple HTTP POST notification to the endpoint provided by the publisher.

DescriptionHTTP Method TypeExpected Response
POST notification with downloadURL to download data from PubMaticPOST

{“queryId”:”1234abc”, “Status”:”COMPLETED”, “downloadURL”:“http://pubmatic_endpoint/v1/analytics/lazy/publisher/artifact/download/{location1}”, "errorCode":null,"errorMessage":null}

Where, “downloadURL”= The endpoint from where data in .csv template can be downloaded. Endpoint is present only if status = “COMPLETED”, otherwise it will be empty.

Possible statuses:

    • COMPLETED: Data is available to be pulled.
    • FAILED: Data pull failed. In this case, there will be an errorCode and an errorMessage as part of the response. Depending upon the error code, we recommend appropriate actions or check with your CSOM/TE. 
If PubMatic does not receive the response, 200 OK, then PubMatic attempts to re-send the notification. 


4. Download data

The publisher can connect to the endpoint shared by PubMatic to download the data in CSV format.

DescriptionMethod PathHTTP Method Type
Download data from PubMatic



PubMatic stores data for a maximum of 90 days after the initial request submission for given queryId.