Getting Started with PubMatic APIs

Note

PubMatic platform users who wish to access our APIs must first register and request an access token. This page provides guidance for this process. It also provides instructions for refreshing access tokens.

UPDATE

On March 31st, 2020 PubMatic deprecated the old API token generation system that relied on Consumer Key and Consumer Secret and replaced it with a new API Authentication service that greatly improves security and usability. In order to continue using our API platform, you must generate a new token in the UI.

PubMatic primary contacts who have had access to the API before should have received a new token via email the week of February 24th, 2020 (Subject: PubMatic API access token creation) and have the new API Access option in the UI. Additional platform users who wish to access our APIs must contact their PubMatic account manager to register and request the API access token.

To ensure PubMatic client data remains private and secure, we require users to register for an API account and request an access token. Once you have completed this process you can access our APIs to retrieve data associated with your specific publisher ID(s). To help you get started as quickly as possible, we've created self-guided processes for:

Once you receive your access token, refer to our documentation for instructions on using our APIs:

New User Registration

This must be done before you can request an access token.

  1. Contact your account manager to request the account.
  2. Once your account is created you will receive an email that contains your API login ID and instructions for creating a password.

Two things to note:

  • Passwords must contain the following:
    • A minimum of eight characters

    • At least one number

    • At least one upper case letter

  • The password link is valid for seven days. If the password link has expired, click the password reset link located in the email.

Generating an access token for the first time

There are two methods for obtaining a new access token:

New users must first register for an account.

The PubMatic API access token should only be generated once for the first-time setup. After it is created, set up a scheduled refresh to occur every 55 days. (Token expires after 60 days.) Use the instructions and samples for both the first-time access token generation and scheduled refresh of the access token provided below and view the associated code samples and instructions in Updating the PubMatic API access token documentation. 

Generating an access token in the UI

Use the following to generate an access token in the Publisher UI.

  1. Log in to the PubMatic platform and navigate to the Account Settings menu in the top-right corner of the screen. Select API Access from the drop-down menu.



  2. Your email address will appear on the page. Confirm that it's correct and then click Generate API Token. If your email address is not correct, contact your account manager to have it corrected.

  3. You will receive a second email that contains your access token. Use this access token to access API data associated with your publisher ID.

Access tokens expire every 60 days:

To prevent a disruption in your ability to access PubMatic APIs, you should refresh your access token before the 60th day. You will not receive a notice before it expires, so be sure to track this time period.

See Refreshing an access token below for instructions.

Generating an access token using user credentials (using the API)

Warning: 200 token generation attempts in 20 minutes exceeds the allowable limit and will automatically disable the user account. 


Use the following to generate the access token using your account credentials.

This API should be executed only once for a user and should not be executed multiple times.


URL:  http://api.pubmatic.com/v1/developer-integrations/developer/token
Method: POST
Headers:
Content-Type: application/json

Request body
{
    "userName" : "<username-email>", - Mandatory
    "password": "<password>", - Mandatory
    "apiProduct" : "PUBLISHER" - Optional 
}


Response body
{
    "userEmail": "<username-email>",
    "tokenType": "BearerToken",
    "accessToken": "<NEW-ACCESS-TOKEN>",
    "refreshToken": "<NEW-REFRESH-TOKEN>"
}
Example
Sample Example :

curl -X POST \
  http://api.pubmatic.com/v1/developer-integrations/developer/token \
  -H 'Content-Type: application/json' \
  -d '{
    "userName" : "<username-email>",
    "password": "<password>"
}'

Refreshing an access token

There are two methods for refreshing an expired access token:

  • Manual Refresh
  • Programmatic Refresh

Refreshing an access token in the UI

To manually refresh access tokens:

  1. Log in to the PubMatic platform and navigate to the Account Settings menu in the top-right corner of the screen. Select API Access from the drop-down menu.



  2. Your email address will appear on the page. Confirm that it's correct and then click Generate API Token. If your email address is not correct, contact your account manager to have it corrected.

  3. You will receive an email that contains a new access token each time you perform a refresh.
  4. Replace your old access token with the new one.

Refreshing an access token using the API

To refresh access tokens programmatically:

  1. Using your most up-to-date refresh token (from a previous manual or programmatic refresh), perform an API call as specified below.
  2. The API call will return the new access token in the response JSON as well as in a confirmation email that contains the new access token. 
  3. Replace the old access token with the new one.

Request Header

Header nameType
Authorization

Bearer <PREVIOUS_ACCESS_TOKEN>

Content-Typeapplication/json

Request Body

Request body
{ 
      "email" : "<user_email>", 
      "apiProduct" : "PUBLISHER", 
      "refreshToken" : "<REFRESH_TOKEN>"
}
Response body
{
    "userEmail": "<username-email>",
    "tokenType": "BearerToken",
    "accessToken": "<NEW-ACCESS-TOKEN>",
    "refreshToken": "<NEW-REFRESH-TOKEN>"
} 
Example
Sample Example :
 curl -X PUT \
 http://api.pubmatic.com/v1/developer-integrations/developer/refreshToken \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer <TOKEN>"
  -d '{ "email" : "<username-email>","apiProduct" : "PUBLISHER","refreshToken" : "<REFRESH_TOKEN>"}' 

How to complete the request

VariableFieldDescription
"email"

"<user_email>"

This field must contain the API user's email address.
"apiProduct"

"PUBLISHER"

This (i.e., "PUBLISHER", ) is the actual value required for the apiProduct variable. Do not use any other value here.
"refreshToken"

"<REFRESH_TOKEN>"

The current token in use (received via confirmation email).

Errors

Below are the common HTTP status codes sent in REST API response by PubMatic API platform.

StatusTextDescription
200OKIndicates that the request has been successfully processed; check contents of body.
DI_0001Internal Server ErrorIndicates the wrong value has been provided, for example using "apiProduct": "123456", will result in an error, as the correct value is "apiProduct": "PUBLISHER",{{}} 


⇧ Top

Do you have feedback on this document? Let us know: email us.

Table of Contents