Getting Started with PubMatic APIs

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

To ensure PubMatic client data remains private and secure, users must register for an API account and request an access token. Once you have completed this process you can access PubMatic 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, see the following documentation for using PubMatic APIs:

New user registration

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

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

Password requirements:

  • 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.

Generate 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.

Generate the PubMatic API access token only once for the first-time setup. After it is created, set up a scheduled refresh to occur every 55 days— access tokens expire after 60 days. Use the instructions and code samples below for both first-time access token generation and scheduled token refresh. Learn more at, Updating the PubMatic API access token

Generate 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 Refresh an access token below for instructions.

Generate an access token with user credentials (using the API)

Warning:

200 token generation attempts within 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.

Execute this API only once for a user—do not execute 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>"
}'

Refresh an access token

There are two methods to refresh an expired access token:

Refresh 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.

Refresh 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 shown below.
  2. The API call returns a new access token in the response JSON as well as in a confirmation email containing the new token. 
  3. Replace your old access token with the new one.
URIhttp://api.pubmatic.com/v1/developer-integrations/developer/refreshToken
MethodPUT

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