Page tree


Before using PubMatic APIs, first generate the API Token. For more information see,  Getting Started with PubMatic APIs
This document supports a set of APIs for older integrations.

Demand Partners can opt to receive mobile parameters inline over API.
Parameters shall be shared in the API request through HTTP POST mechanism and data formatted in JSON. Only available parameters would be added into the JSON Structure. If the impression is not a mobile impression, then the POST data will not contain “mobile” object.


Example JSON
Content-Type: application/json
Content-Length: <length>
{"exclude": {
  .............
  },
  "site_richmedia_attributes” : {
    .............
  },
  "contextual_brand_safety_data":[........],
  "mobile" : {
    "device" : {
      "did" : "123456",
      "dpid" : "3456789",
      "dpidtype" : "3",
      "carrier" : "att",
      "nettype" : "wifi",
      "devicetype" : 1,
      "make" : "Apple",
      "model" : "iPhone",
      "os" : "iOS",
      "osv" : "3.1.2",
      "js" : 1,
      "loc" : "41.906365,-75.327759"
    },
    "origin" : {
      "aid": "XXXXXXXX",
      "name": "PubMatic Test App",
      "storeurl": "https://itunes.apple.com/us/app/PubMaticTestApp/idXXXXXXXX?mt=8",
      "ver": "0.1.2",
      "bundle": "com.pubmatic.test",
      "api": [3,4,5],
      "domain": "http: //www.pubmatic.com",
      "cat": [
        "IAB9",
        "IAB1",
        "IAB9-30"
      ],
      "paid": 0
    },
    "user" : {
      "yob" : "1970",
      "gender" : "F",
      "ethnicity" : "0",
      "income" : "$12000"
      "city" : "New York"
      "state" : "NY"
      "dma" : 734,
      "zip" : "12345",
      "geo_type" : 2,
      "keywords" : "news, technology"
    },
    "misc" : {
      "ormma" : 1,        
      "adOrientation" : 1,
      "deviceOrientation" : 1,
      "adRefreshRate" : 2
    }  
  }
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Mobile Parameters Format

This section consists of the following sub-sections:

  • Device Object Parameters
  • Origin Object Parameters
  • User Object Parameters

Device Object Parameters

Property

Mandatory

Multi Valued

Description

did

No

No

SHA1 hashed device ID; IMEI when available, else MEID or ESN.


If the user has either opted out of the PubMatic system OR has the “do not track” header enabled in the user’s browser (HTTP_DNT = 1), then this parameter is not passed in the RTB request.

dpid

No

No

A unique platform-specific identifier for the “dpidtype” parameter mentioned below (e.g., Android ID or UDID for iOS).


If the user has either opted out of the PubMatic system OR has the “do not track” header enabled in the user’s browser (HTTP_DNT = 1), then this parameter is not passed in the RTB request.

dpidtype

No

No

Type of the ID specified in the “dpid” parameter above. Possible values are:


If the user has either opted out of the PubMatic system OR has the “do not track” header enabled in the user’s browser (HTTP_DNT = 1), then this parameter is not passed in the RTB request.

dpidhash

No

No

Type of algorithm used for hashing the device identifier provided in the dpid parameter mentioned above. Possible values are:

  • 0 - Unknown

  • 1 - Raw

  • 2 - SHA1

  • 3 - MD5

country

No

No

Country derived from the IP address using ISO-3166-1 Alpha-3.

carrier

No

No

Carrier or ISP derived from the IP address.

nettype

No

No

Type of connection. Possible values are “wifi” and “cellular”.

devicetype

No

No

Type of device according to the open RTB standards. (Example: 1)

  • 1 - Mobile/Tablet
  • 2 - PC
  • 3 - Smart TV
  • 5 – Tablet


If the user has either opted out of the PubMatic system OR has the “do not track” header enabled in the user’s browser (HTTP_DNT = 1), then this parameter is not passed in the RTB request.

make

No

No

Device make (Example: Apple).

model

No

No

Device model (Example: iPhone).

os

No

No

Device operating system (Example: iOS).

osv

No

No

Device operating system version (Example: 3.1.2).

js

No

No

1 if the device supports JavaScript; else 0.

loc

No

No

Latitude/Longitude values, such as 41.906365, -75.327759 (South and West are depicted as negative numbers).

This parameter is populated only when “geo.loc_source=1”.



Origin Object Parameters

Property

Mandatory

Multi Valued

Description

aid

No

No

Application ID on the exchange (Only in case of app view)

name

No

No

Name of the mobile application.

storeurl

No

No

App store’s URL for the mobile application.

ver

No

No

Application version

bundle

No

No

Application bundle of package name (for example, com.foo.mygame). This is intended to be a unique ID across multiple exchanges.

api

No

Yes (Array of Integer)

List of supported API frameworks for the impression. If an API value is not explicitly listed, then it is assumed to be not supported. Possible values are:

  • 1 - VPAID 1.0

  • 2 - VPAID 2.0

  • 3 - MRAID 1.0

  • 4 - ORMMA

  • 5 - MRAID 2.0

domain

No

No

Domain of the mobile application, for example, ”mygame.foo.com”.

cat

No

Array of strings

Array of IAB categories for the overall application. To view the list of content categories, refer to the IAB Categories List table in the Reference section of this document.

paid

No

No

1 if the application is a paid version; else 0 (that is, free).


User Object Parameters

Property

Mandatory

Multi Valued

Description

yob*

No

No

Year of birth as a 4-digit integer.


If the user has either opted out of the PubMatic system OR has the “do not track” header enabled in the user’s browser (HTTP_DNT = 1), then this parameter is not passed in the RTB request.

gender*

No

No

Gender as M male, F female, O other.

If the user has either opted out of the PubMatic system OR has the “do not track” header enabled in the user’s browser (HTTP_DNT = 1), then this parameter is not passed in the RTB request.

ethnicity*

No

No

Ethnicity of the user (Example: 0). Possible options are:

  • 0 - Hispanic

  • 1 - African-American

  • 2 - Caucasian

  • 3 - Asian-American

  • 4 - Other


If the user has either opted out of the PubMatic system OR has the “do not track” header enabled in the user’s browser (HTTP_DNT = 1), then this parameter is not passed in the RTB request.

income*

No

No

Income of the user.

If the user has either opted out of the PubMatic system OR has the “do not track” header enabled in the user’s browser (HTTP_DNT = 1), then this parameter is not passed in the RTB request.

city*

No

No

City of the user (Example:  New York).

state*

No

No

State of the user (Example:  NY).

dma*

No

No

Designated Market Area of the user (Example:  734).

zip*

No

No

Home zip code if USA; else postal code.

geo_type*

No

No

Type of geographical source (Example: 1).

  • 1 - GPS or location

  • 2 - IP address

  • 3 - user-provided

keywords*

No

No

Comma separated list of keywords of consumer interests or intent

ormma

No

No

Minimum compliance level required.

adOrientation

No

No

Ad orientation ID for given ad request.

deviceOrientation

No

No

Device orientation ID.

adRefreshRate

No

No

Number of times ad is refreshed per minute.

* All the parameters in the above table marked with an asterisk (*) will be deprecated soon from Mobile Parameters. They are already included in User Parameters mentioned below (which will support both mobile and display). Please plan to make the necessary changes before these parameters are deprecated later in 2014 (date to be determined).


⇧ Top