Targeting APIs (for Publishers & Demand Partners)

Document created by pubmatic-archivist on Mar 27, 2017Last modified by catherine.racette on Aug 30, 2017
Version 19Show Document
  • View in full screen mode

Description

Targeting consists of various targeting parameters which you can then associate with a product. These APIs allows a user to create and manage targeting in the PubMatic system.

The Targeting APIs are part of Inventory APIs. To learn more about Inventory APIs, refer to Inventory Overview for more information.

                   

Methods

                                 

Method Path
HTTP Method Type
Description
Link to Definition
/targeting
POST
Create new targeting in the PubMatic system

Create Targeting

/targeting/{id}GETRetrieve the details of a specific targetingRetrieving Details of Targeting
/targetingGETRetrieve the list of targetingRetrieving List of Targeting Details (for Publishers)
/targetingGETRetrieve the list of targetingRetrieving List of Targeting Details (for Demand Partners)
/targeting/{id}PUTUpdate the details of a specific targeting

Updating Targeting

/targeting/{id}DELETEDelete targeting details.

Deleting Targeting Details

 

 

Create Targeting

Overview

This API allows you to create a targeting in the PubMatic system.

Request

         
URL
$URI_PREFIX/targeting

 

Note: For sandbox testing, $URI_PREFIX should be replaced with "http://api-sandbox.pubmatic.com/v1/inventory".

 

For production, $URI_PREFIX should be replaced with "http://api.pubmatic.com/v1/inventory/".
HTTP MethodPOST

Request Headers

                 

Header Name
Type
Value
Required
Description
Authorization
String
Bearer ${access_token}
Yes

Publisher Token to authenticate and authorize the user calling the Unified Ad Server API. Send the access token generated for authentication at the place of ${access_token} in the request.

 

For more information about access tokens, refer to Getting Started with PubMatic APIs.

Request Body

                                                                                                                                                                                  

Body Parameter
Type
Required
Validations
Description
name
String
No
  • Maximum length is 250 characters
  • Name should be unique for your account
  • Unsupported characters are |!{}[]^"~*?:;+\
Name of the targeting
description
String
No
  • Maximum length is 250 characters
  • Unsupported characters are |!{}[]^"~*?:;+\
Description of the targeting
geos
JSON Array of Integer
No
Value should already exist in the system
Geos to be associated with the targeting
For example, US, Canada, New York
zips
JSON Array of Integer
No
 
Zips for Targeting
e.g. 453216
audienceSegments
JSON Array of Integer
No
Value should already exist in the system
Custom audience segments to be associated with the targeting
pixel (Inclusion/Exclusion)
JSON Array of Integer
No
Value should already exist in the system
Targeting/Re-targeting pixels to be included in the targeting (pixel.includes) and/or excluded from the targeting unit (pixel.excludes)
daysOfWeek
JSON Array of Integer
No
Value should already exist in the system
Days of the week on which the targeting will be applicable
startTimeParting
Timestamp
No
HH:MM:SS
Time of the day from which the targeting will be applicable
endTimeParting
Timestamp
No
HH:MM:SS
Time of the day till which the targeting will be applicable
browsers
JSON Array of Integer
No
Value should already exist in the system
Browsers to be associated with the targeting
For example, IE, Firefox, etc.
connectionTypes
JSON Array of Integer
No
Value should already exist in the system
Connection types to be associated with the targeting
For example, Cellular, Dialup, etc.
osTypes
JSON Array of Integer
No
Value should already exist in the system
OS types to be associated with the targeting
For example, iOS, Android, etc.
os
JSON Array of Integer
No
Value should already exist in the system
IDs of the OSs to be associated with the targeting
carriers
JSON Array of Integer
No
Value should already exist in the system
 
Mobile carriers to be associated with the targeting
latLong
Boolean
No
Should be a valid Boolean value
Indicates whether latitude/longitude targeting should be enabled in the targeting or not.
deviceIdType
Integer
No
Value should already exist in the system
 
Types of device IDs to be associated with the targeting. Possible options are:
1 - IDFA
3 - Android ID
videoAdTypes
JSON Array of Integer
No
Value should already exist in the system
Types of video ads to be associated with the targeting
For example, Linear, Non-Linear, etc.
videoAdPositions
JSON Array of Integer
No
Value should already exist in the system
Video ad positions to be associated with the targeting
For example, Pre-roll, Post-roll, etc.
videoPlaybackMethods
JSON Array of Integer
No
Value should already exist in the system
 
Video Playback methods to be associated with the targeting
For example, 'Auto-play sound on', Click-to-play, etc.
preset
Boolean
No
Should be a valid Boolean value
Indicates whether the targeting should be saved as a preset for future use or not.
richMediaTechnologies
JSON Array of Integer
No
Value should already exist in the system
 
Rich Media Technologies for targeting
For example,  Eyeblaster , Pointroll
matchedUsers
Boolean
No
Valid boolean value
Indicates whether cookies are placed on visitor's browser or not
smartphones
JSON Array of Integer
No
Value should already exist in the system
Smart phone devices for targeting
For example, Smart Phone
tablets
JSON Array of Integer
No
Value should already exist in the system
Tablet devices for targeting
For example, Tablet
ownerTypeId
Integer
Yes

Possible values are:

 

Type of AccountValue
Publisher1
Demand Partner5
ATD/Buyer7
Indicates the type of account of the user invoking this API.
ownerId
Long
Yes

Should be a valid Publisher ID, DSP, or Buyer ID

Indicates account ID

Sample Request

POST $URI_PREFIX/targeting

{
  "name": "test_for_targeting",
  "description": "test description for Targeting",
  "geos": [
    5,
    6
  ],
  "audienceSegments": [
    1,
    2
  ],
  "daysOfWeek": [
    1,
    2,
    3,
    4,
    5,
    6,
    7
  ],
  "startTimeParting": "00:00:00",
  "endTimeParting": "08:00:00",
  "browsers": [
    4
  ],
  "connectionTypes": [
    4
  ],
  "os": [
    10
  ],
  "osTypes": [
    2
  ],
  "smartphones": [
    575
  ],
  "tablets": [
    94,
    96
  ],
  "carriers": [
    309
  ],
  "latLong": false,
  "deviceIdType": [
    1
  ],
  "videoAdTypes": [
    1
  ],
  "videoAdPositions": [
    2
  ],
  "videoPlaybackMethods": [
    3
  ],
  "preset": true,
  "richMediaTechnologies": [
    1
  ],
  "ownerId": 12345,
  "ownerType": 1
}

 

Response

Response Body

           
Type
Description
Targeting objectJSON response of successfully-created targeting unit

Sample Response

{
    "id": 1,
    "name": "test_for_targeting",
    "description": "test description for Targeting",
    "geos": [
        {
            "id": 5,
            "name": "Afghanistan",
            "uri": "$URI_PREFIX/common/geo/5",
            "geoLevel": "COUNTRY"
        },
        {
            "id": 6,
            "name": "Antigua and Barbuda",
            "uri": "$URI_PREFIX/common/geo/6",
            "geoLevel": "COUNTRY"
        }
    ],
    "audienceSegments": [
        {
            "id": 1,
            "name": "Students",
            "uri": "$URI_PREFIX/audiences/1"
        },
        {
            "id": 2,
            "name": "Auto",
            "uri": "$URI_PREFIX/audiences/2"
        }
    ],
    "pixel": {
        "includes": [
            {
                "id": 3,
                "name": "TestPixel"
            }
        ],
        "excludes": [
            {
                "id": 4,
                "name": "TestPixel1"
            }
        ]
    },
    "daysOfWeek": [
        {
            "id": 7,
            "name": "Sunday"
        },
        {
            "id": 6,
            "name": "Saturday"
        },
        {
            "id": 5,
            "name": "Friday"
        },
        {
            "id": 4,
            "name": "Thursday"
        },
        {
            "id": 3,
            "name": "Wednesday"
        },
        {
            "id": 2,
            "name": "Tuesday"
        },
        {
            "id": 1,
            "name": "Monday"
        }
    ],
    "startTimeParting": "00:00:00",
    "endTimeParting": "08:00:00",
    "browsers": [
        {
            "id": 4,
            "name": "Opera",
            "uri": "$URI_PREFIX/common/browser/4"
        }
    ],
    "connectionTypes": [
        {
            "id": 4,
            "name": "Dialup"
        }
    ],
    "osTypes": [
        {
            "id": 2,
            "name": "Android"
        }
    ],
    "os": [
        {
            "id": 10,
            "name": "Android 1",
            "uri": "http://172.16.4.66:8080/common/mobileOS/10"
        }
    ],
    "carriers": [
        {
            "id": 309,
            "name": "Three",
            "uri": "http://172.16.4.66:8080/common/mobileCarrier/309"
        }
    ],
    "latLong": false,
    "deviceIdType": [
        {
            "id": 1,
            "name": "IDFA"
        }
    ],
    "videoAdTypes": [
        {
            "id": 1,
            "name": "Linear"
        }
    ],
    "videoAdPositions": [
        {
            "id": 1,
            "name": "Pre-roll"
        }
    ],
    "videoPlaybackMethods": [
        {
            "id": 3,
            "name": "Click-to-play"
        }
    ],
    "preset": true,
    "creationTime": "2014-09-24T21:46:42Z",
    "modificationTime": "2014-10-07T17:55:35Z",
    "deleted": false,
    "richMediaTechnologies": [
        {
            "id": 1,
            "name": "Pointroll",
            "uri": "$URI_PREFIX/common/richMediaTechnology/1"
        }
    ],
    "smartphones": [
        {
            "id": 575,
            "name": "Nokia All Other Smart Phones"
        }
    ],
    "tablets": [
        {
            "id": 94,
            "name": "Sony Tablet S"
        },
        {
            "id": 96,
            "name": "HP Touch Pad"
        }
    ]
}

 

Error Codes

Error Codes:

                                                                                                                                                           
Error code
Description
IU_001_0007Invalid or null value for Publisher ID.
TU_001_0001Invalid targeting unit ID.
TU_001_0002Invalid user ID.
TU_001_0003Name cannot exceed 255 characters.
TU_001_0004Description cannot exceed 512 characters.
TU_001_0005Invalid or null value for Owner Type field.
TU_001_0006Invalid owner ID.
TU_001_0008Error in validating publisher info.
TU_001_0009Invalid or null value for Owner Type field.
TU_001_0010Invalid Audience Segments selected.
TU_001_0011Invalid Geos selected.
TU_001_0012Internal error in validating selected Geos.
TU_001_0013Invalid Browser IDs passed.
TU_001_0014Invalid Mobile OS IDs passed.
TU_001_0016Invalid Connection type IDs passed.
TU_001_0018Invalid Mobile Carrier IDs passed.
TU_001_0019Invalid Phone Type IDs passed.
TU_001_0020Invalid Video Playback Method IDs passed.
TU_001_0021Invalid Video Position IDs passed.
TU_001_0022Invalid Mobile OS type IDs passed.
TU_001_0023Invalid Geo IDs passed.
TU_001_0025Invalid Video Type IDs passed.
TU_001_0026Invalid Resource Type found for logged in user.
TU_001_0027Mobile OS IDs are not mapped to Mobile OS Type IDs.
TU_001_0029Invalid Days Of Week IDs passed.
TU_001_0030Invalid Device ID Types passed.
TU_001_0031Targeting creation failed
TU_001_0032End time parting cannot be before start time parting.
TU_001_0033Targeting name already exists. Please use another name.
TU_001_0034Demand Partner/ATD not supported
TU_001_0035Invalid Targeting name. Following characters are not allowed: |!{}[]^"~*?:;+\
TU_001_0036Invalid Targeting description. Following characters are not allowed: |!{}[]^"~*?:;+\
TU_001_0037Invalid Pixels passed.
TU_001_0038Targeting name cannot be null, if preset is set to true.
TU_001_0045Invalid Rich Media Technology ID passed.
TU_001_0048Invalid Smartphone IDs passed.
TU_001_0049Invalid Tablets IDs passed.

 

Sample error response

 

[
    {
        "errorCode": "TU_001_0010",
        "errorMessage": "Invalid Audience Segments selected."
    }
]

 

 

Retrieving Details of Targeting

Overview

This API allows you to retrieve the details of a specific targeting using by the "id" parameter.

Request

         
URI$URI_PREFIX/targeting/{id}

 

Note: For sandbox testing, $URI_PREFIX should be replaced with "http://api-sandbox.pubmatic.com/v1/inventory".

 

For production, $URI_PREFIX should be replaced with "http://api.pubmatic.com/v1/inventory/".
HTTP MethodGET

Request Headers

                 

Header Name
Type
Value
Required
Description
Authorization
String
Bearer ${access_token}
Yes
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

Path Parameters

               
Parameter Name
Type
Required
Description
id
Long
Yes
ID of the targeting whose details need to be fetched.
For example, 123

Query Parameters

Parameter Name
Type
Required
Description
loggedInOwnerTypeId
Integer
Yes

Indicates the type of account of the user invoking this API. Possible values are:

 

Type of AccountValue
Publisher1
Demand Partner5
ATD/Buyer7
loggedInOwnerId
Long
Yes

Indicates account ID

 

Sample Request


GET $URI_PREFIX/targeting/123?filters=loggedInOwnerTypeId eq 1&filters=loggedInOwnerId eq 12345

Response

Response Body

           
Type
Description
JSON for the record objectDetails of the targeting

Sample Response

 

{
"id": 123,
"name": "test_for_targeting",
"description": "test description for Targeting",
"geos": [
{
"id": 5,
"name": "Afghanistan",
"uri": "$URI_PREFIX/common/geo/5",
"geoLevel": "COUNTRY"
},
{
"id": 6,
"name": "Antigua and Barbuda",
"uri": "$URI_PREFIX/common/geo/6",
"geoLevel": "COUNTRY"
}
],
"audienceSegments": [
{
"id": 1,
"name": "Students",
"uri": "$URI_PREFIX/audiences/1"
},
{
"id": 2,
"name": "Auto",
"uri": "$URI_PREFIX/audiences/2"
}
],
"pixel": {
"includes": [
{
"id": 3,
"name": "TestPixel"
}
],
"excludes": [
{
"id": 4,
"name": "TestPixel1"
}
]
},
"daysOfWeek": [
{
"id": 7,
"name": "Sunday"
},
{
"id": 6,
"name": "Saturday"
},
{
"id": 5,
"name": "Friday"
},
{
"id": 4,
"name": "Thursday"
},
{
"id": 3,
"name": "Wednesday"
},
{
"id": 2,
"name": "Tuseday"
},
{
"id": 1,
"name": "Monday"
}
],
"startTimeParting": "00:00:00",
"endTimeParting": "08:00:00",
"browsers": [
{
"id": 4,
"name": "Opera",
"uri": "$URI_PREFIX/common/browser/4"
}
],
"connectionTypes": [
{
"id": 4,
"name": "Dialup"
}
],
"osTypes": [
{
"id": 2,
"name": "Android"
}
],
"os": [
{
"id": 10,
"name": "Android 1",
"uri": "http://172.16.4.66:8080/common/mobileOS/10"
}
],
"carriers": [
{
"id": 309,
"name": "Three",
"uri": "http://172.16.4.66:8080/common/mobileCarrier/309"
}
],
"latLong": false,
"deviceIdType": [
{
"id": 1,
"name": "IDFA"
}
],
"videoAdTypes": [
{
"id": 1,
"name": "Linear"
}
],
"videoAdPositions": [
{
"id": 1,
"name": "Pre-roll"
}
],
"videoPlaybackMethods": [
{
"id": 3,
"name": "Click-to-play"
}
],
"preset": true,
"creationTime": "2014-09-24T21:46:42Z",
"modificationTime": "2014-10-07T17:55:35Z",
"deleted": false,
"richMediaTechnologies": [
{
"id": 1,
"name": "Pointroll",
"uri": "$URI_PREFIX/common/richMediaTechnology/1"
}
],
"smartphones": [
{
"id": 575,
"name": "Nokia All Other Smart Phones"
}
],
"tablets": [
{
"id": 94,
"name": "Sony Tablet S"
},
{
"id": 96,
"name": "HP Touch Pad"
}
]
}

Error Codes

                   

Error code
Description
TU_001_0039
No targeting found for given targeting ID.
TU_001_0040
Error in fetching targeting details.
CC02_0006
User is not allowed to access this resource

 

Sample error response

 

[
    {
        "errorCode": "TU_001_0039",
        "errorMessage": "No targeting found for given targeting Id"
    }
]

Retrieving List of Targeting Details (for Publishers)

Overview

This API allows you to retrieve a list of targeting matching the specified filter parameters. Various filter parameters can be applied to narrow down the search results.

Request

         
URI$URI_PREFIX/targeting

 

Note: For sandbox testing, $URI_PREFIX should be replaced with "http://api-sandbox.pubmatic.com/v1/inventory".

 

For production, $URI_PREFIX should be replaced with "http://api.pubmatic.com/v1/inventory/".
HTTP MethodGET

Request Headers

                 
Header Name
Type
Value
Required
Description
Authorization
String
Bearer ${access_token}
Yes
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

Request Query Parameters

                                      
Parameter Name
Type
Required
Validations
Description
pageSize
Integer
No
 
Maximum number of rows to be included in the response.
Default value: 100
pageNumber
Integer
No
 
Page number to be fetched in case of multiple pages.
Default value: 1
filters
String
No
Values must be from those mentioned below in the supported Dimensions section.
Filters that restrict the data returned for your request.
For more details, refer the Reporting and Listing API Request Details section.
sort
String
No
Values must be from those mentioned below in the supported Dimensions section.
A list of comma-separated dimensions indicating the sorting order and sorting direction for the returned data.
For more details, refer the Reporting and Listing API Request Details section.

Searchable Fields

                                                    

Name

Data type

Summary

Sample Filter Data

Sample Sort Data

id

Long

Searching and Sorting is supported

?filters=id gtEq 298&filters=id lt 301

For ascending order, use ?sort=id

For descending order, use ?sort=-id

name

String

Searching and Sorting is supported

?filters=name like test

For ascending order, use ?sort=name

For descending order, use ?sort=-name

description

String

Searching and Sorting is supported

?filters=description like test

 For ascending order, use ?sort=description

For descending order, use ?sort=-description

daysOfWeek

Integer

Searching and Sorting is not supported

daysOfWeek eq 1
((1-7) denotes Mon-Sun) 

?sort=daysOfWeek

deviceIdType

Integer

Searching and Sorting is not supported

deviceIdType.id eq 1
( 1 - IDFA , 3-Android ID)

?sort=deviceIdType

latLong

Boolean

Searching and Sorting is not supported

?filters=latLong eq false

From top onwards, use ?sort=latLong

loggedInOwnerTypeId

Integer

Indicates type of account:

Publisher - 1

Demand Partner - 5

Buyer/ATD - 7

&filters=loggedInOwnerTypeId eq 1

 

loggedInOwnerId

Long

Account ID

&filters=loggedInOwnerId eq 12345

 

Note: For more details on the filter and sort parameters, refer the Reporting and Listing API Request Details page. notLike filter operator is not supported.

                       

Sample Request

GET $URI_PREFIX/targeting?filters=loggedInOwnerTypeId eq 1&filters=loggedInOwnerId eq 12345&pageSize=25&pageNumber=1&filters=name like test

Response

Response Headers

                                 
Response Header Name
Value
Description
Transfer-Encoding
chunked
 
Status Code
200
OK
Server
Apache-Coyote/1.1
 
Date
Fri, 30 May 2014 06:45:05 GMT
 
Content-Type
application/json
Mediatype that is to be returned in search/sort operation

Response Body

                  
Response Body Parameter
Type
Description
metaDataJSON Object Metadata about the generated response.
itemsJSON Array of record objectRecords generated as per your request.

Sample Response


{
"metaData": {
"startIndex": 1,
"request": {
"pageSize": 15,
"pageNumber": 1,
"metrics": null,
"dimensions": null,
"sort": null,
"filters": [
"id eq 1"
],
"fromDate": null,
"toDate": null,
"useAllDimensions": true
},
"totalRecords": 1,
"endIndex": 1
},
"items": [
{
"id": 38879,
"name": "hello new",
"description": "world",
"preset": true,
"creationTime": "2014-09-24T21:46:42Z",
"modificationTime": "2014-10-07T17:55:35Z",
"deleted": false,
"richMediaTechnologies": [
{
"id": 1,
"name": "Pointroll",
"uri": "$URI_PREFIX/common/richMediaTechnology/1"
}
],
"geos": [
{
"id": 5,
"name": "Afghanistan",
"uri": "$URI_PREFIX/common/geo/5",
"geoLevel": "COUNTRY"
},
{
"id": 6,
"name": "Antigua and Barbuda",
"uri": "$URI_PREFIX/common/geo/6",
"geoLevel": "COUNTRY"
}
],
"audienceSegments": [
{
"id": 1,
"name": "Students",
"uri": "$URI_PREFIX/audiences/1"
},
{
"id": 2,
"name": "Auto",
"uri": "$URI_PREFIX/audiences/2"
}
],
"daysOfWeek": [
{
"id": 7,
"name": "Sunday"
},
{
"id": 6,
"name": "Saturday"
},
{
"id": 5,
"name": "Friday"
},
{
"id": 4,
"name": "Thursday"
},
{
"id": 3,
"name": "Wednesday"
},
{
"id": 2,
"name": "Tuesday"
},
{
"id": 1,
"name": "Monday"
}
],
"startTimeParting": "00:00:00",
"endTimeParting": "23:59:59",
"browsers": [
{
"id": 4,
"name": "Opera",
"uri": "$URI_PREFIX/common/browser/4"
},
{
"id": 2,
"name": "Firefox",
"uri": "$URI_PREFIX/common/browser/2"
}
],
"connectionTypes": null,
"osTypes": [
{
"id": 10,
"name": "Palm OS"
}
],
"os": [
{
"id": 80,
"name": "Palm OS 5.4",
"uri": "$URI_PREFIX/common/mobileOS/80"
},
{
"id": 81,
"name": "Palm OS 5.5",
"uri": "$URI_PREFIX/common/mobileOS/81"
}
],
"carriers": [
{
"id": 347,
"name": "Vodafone",
"uri": "$URI_PREFIX/common/mobileCarrier/347"
},
{
"id": 350,
"name": "Vodafone Australia",
"uri": "$URI_PREFIX/common/mobileCarrier/350"
}
],
"latLong": true,
"smartphones": [
{
"id": 575,
"name": "Nokia All Other Smart Phones"
}
],
"tablets": [
{
"id": 94,
"name": "Sony Tablet S"
},
{
"id": 96,
"name": "HP Touch Pad"
}
],
"deviceIdType": [
{
"id": 1,
"name": "IDFA"
}
],
"videoAdTypes": [
{
"id": 1,
"name": "Linear"
}
],
"videoAdPositions": [
{
"id": 1,
"name": "Pre-roll"
},
{
"id": 3,
"name": "Post-roll"
}
],
"videoPlaybackMethods": [
{
"id": 3,
"name": "Click-to-play"
},
{
"id": 4,
"name": "Mouse-over"
}
]
}
]
}



Error Codes

               

Error code

Description

TU_001_0043

Publisher ID filter is not applicable for this user.

CC03_0007

Multiple associated resources found during search operation. Pass loggedInOwnerId and loggedInOwnerTypeId in query parameters.

Sample error response


[
    {
        "errorCode": "TU_001_0043",
        "errorMessage": " Publisher ID filter is not applicable for this user."
    }
]

 

 

Retrieving List of Targeting Details (for Demand Partners)

Overview

This API allows you to retrieve a list of targeting matching the specified filter parameters. Various filter parameters can be applied to narrow down the search results.

Request

         
URI

$URI_PREFIX/targeting


Note: For sandbox testing, $URI_PREFIX should be replaced with "http://api-sandbox.pubmatic.com/v1/inventory".

 

For production, $URI_PREFIX should be replaced with "http://api.pubmatic.com/v1/inventory/".
HTTP MethodGET

Request Headers

                 
Header Name
Type
Value
Required
Description
Authorization
String
Bearer ${access_token}
Yes
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

Request Query Parameters

                                      
Parameter Name
Type
Required
Validations
Description
pageSize
Integer
No
 
Maximum number of rows to be included in the response.
Default value: 100
pageNumber
Integer
No
 
Page number to be fetched in case of multiple pages.
Default value: 1
filters
String
No
Values must be from those mentioned below in the supported Dimensions section.
Filters that restrict the data returned for your request.
For more details, refer the Reporting and Listing API Request Details section.
sort
String
No
Values must be from those mentioned below in the supported Dimensions section.
A list of comma-separated dimensions indicating the sorting order and sorting direction for the returned data.
For more details, refer the Reporting and Listing API Request Details section.

Searchable Fields

                                                           

Name

Data type

Summary

Sample Filter Data

Sample Sort Data

id

Long

Searching and Sorting is supported

?filters=id gtEq 298&filters=id lt 301

For ascending order, use ?sort=id

For descending order, use ?sort=-id

name

String

Searching and Sorting is supported

?filters=name like test

For ascending order, use ?sort=name

For descending order, use ?sort=-name

description

String

Searching and Sorting is supported

?filters=description like test

 For ascending order, use ?sort=description

For descending order, use ?sort=-description

publisherId

Long

For fetching targeting belonging to a particular publisher.

?publisherId=1234

 

daysOfWeek

Integer

Searching and Sorting is not supported

daysOfWeek eq 1
((1-7) denotes Mon-Sun) 

?sort=daysOfWeek

deviceIdType

Integer

Searching and Sorting is not supported

deviceIdType.id eq 1
( 1 - IDFA , 3-Android ID)

?sort=deviceIdType

latLong

Boolean

Searching and Sorting is not supported

?filters=latLong eq false

From top onwards, use ?sort=latLong

loggedInOwnerTypeId

Integer

Indicates the type of account. Possible Values:

Type of AccountValue
Publisher1
Demand Partner5
ATD/Buyer7

&filters=loggedInOwnerTypeId eq 5

 

loggedInOwnerId

Long

Account ID

&filters=loggedInOwnerId eq 12345

 

Note: For more details on the filter and sort parameters, refer the Reporting and Listing API Request Details section. notLike filter operator is not supported.

                   

Sample Request


GET $URI_PREFIX/targeting?filters=loggedInOwnerTypeId eq 5&filters=loggedInOwnerId eq 12345&pageSize=25&pageNumber=1&filters=name like test

 

Response

Response Headers

                                 
Response Header Name
Value
Description
Transfer-Encoding
chunked
 
Status Code
200
OK
Server
Apache-Coyote/1.1
 
Date
Fri, 30 May 2014 06:45:05 GMT
 
Content-Type
application/json
Mediatype that is to be returned in search/sort operation

Response Body

                  
Response Body Parameter
Type
Description
metaDataJSON Object Metadata about the generated response.
itemsJSON Array of record objectRecords generated as per your request.

Sample Response

 

{
    "metaData": {
        "startIndex": 1,
        "request": {
            "pageSize": 15,
            "pageNumber": 1,
            "metrics": null,
            "dimensions": null,
            "sort": null,
            "filters": [
                "id eq 1"
            ],
            "fromDate": null,
            "toDate": null,
            "useAllDimensions": true
        },
        "totalRecords": 1,
        "endIndex": 1
    },
    "items": [
        {
            "id": 38879,
            "name": "hello new",
            "description": "world",
            "preset": true,
            "creationTime": "2014-09-24T21:46:42Z",
            "modificationTime": "2014-10-07T17:55:35Z",
            "deleted": false,
            "richMediaTechnologies": [
                {
                    "id": 1,
                    "name": "Pointroll",
                    "uri": "$URI_PREFIX/common/richMediaTechnology/1"
                }
            ],
            "geos": [
                {
                    "id": 5,
                    "name": "Afghanistan",
                    "uri": "$URI_PREFIX/common/geo/5",
                    "geoLevel": "COUNTRY"
                },
                {
                    "id": 6,
                    "name": "Antigua and Barbuda",
                    "uri": "$URI_PREFIX/common/geo/6",
                    "geoLevel": "COUNTRY"
                }
            ],
            "audienceSegments": [
                {
                    "id": 1,
                    "name": "Students",
                    "uri": "$URI_PREFIX/audiences/1"
                },
                {
                    "id": 2,
                    "name": "Auto",
                    "uri": "$URI_PREFIX/audiences/2"
                }
            ],
            "daysOfWeek": [
                {
                    "id": 7,
                    "name": "Sunday"
                },
                {
                    "id": 6,
                    "name": "Saturday"
                },
                {
                    "id": 5,
                    "name": "Friday"
                },
                {
                    "id": 4,
                    "name": "Thursday"
                },
                {
                    "id": 3,
                    "name": "Wednesday"
                },
                {
                    "id": 2,
                    "name": "Tuesday"
                },
                {
                    "id": 1,
                    "name": "Monday"
                }
            ],
            "startTimeParting": "00:00:00",
            "endTimeParting": "23:59:59",
            "browsers": [
                {
                    "id": 4,
                    "name": "Opera",
                    "uri": "$URI_PREFIX/common/browser/4"
                },
                {
                    "id": 2,
                    "name": "Firefox",
                    "uri": "$URI_PREFIX/common/browser/2"
                }
            ],
            "connectionTypes": null,
            "osTypes": [
                {
                    "id": 10,
                    "name": "Palm OS"
                }
            ],
            "os": [
                {
                    "id": 80,
                    "name": "Palm OS 5.4",
                    "uri": "$URI_PREFIX/common/mobileOS/80"
                },
                {
                    "id": 81,
                    "name": "Palm OS 5.5",
                    "uri": "$URI_PREFIX/common/mobileOS/81"
                }
            ],
            "carriers": [
                {
                    "id": 347,
                    "name": "Vodafone",
                    "uri": "$URI_PREFIX/common/mobileCarrier/347"
                },
                {
                    "id": 350,
                    "name": "Vodafone Australia",
                    "uri": "$URI_PREFIX/common/mobileCarrier/350"
                }
            ],
            "latLong": true,
            "smartphones": [
                {
                    "id": 575,
                    "name": "Nokia All Other Smart Phones"
                }
            ],
            "tablets": [
                {
                    "id": 94,
                    "name": "Sony Tablet S"
                },
                {
                    "id": 96,
                    "name": "HP Touch Pad"
                }
            ],
            "deviceIdType": [
                {
                    "id": 1,
                    "name": "IDFA"
                }
            ],
            "videoAdTypes": [
                {
                    "id": 1,
                    "name": "Linear"
                }
            ],
            "videoAdPositions": [
                {
                    "id": 1,
                    "name": "Pre-roll"
                },
                {
                    "id": 3,
                    "name": "Post-roll"
                }
            ],
            "videoPlaybackMethods": [
                {
                    "id": 3,
                    "name": "Click-to-play"
                },
                {
                    "id": 4,
                    "name": "Mouse-over"
                }
            ]
        }
    ]
}

Error Codes

               

Error code

Description

TU_001_0043

Publisher ID filter is not applicable for this user.

CC03_0007

Multiple associated resources found during search operation. Pass loggedInOwnerId and loggedInOwnerTypeId in query parameters.

Sample error response


[
    {
        "errorCode": "TU_001_0043",
        "errorMessage": " Publisher ID filter is not applicable for this user."
    }
]

 

 

 

Updating Targeting

Overview

This API allows you to update a specific targeting unit in the PubMatic system.

Request

         
URI
$URI_PREFIX/targeting/{id}

 

Note: For sandbox testing, $URI_PREFIX should be replaced with "http://api-sandbox.pubmatic.com/v1/inventory".

 

For production, $URI_PREFIX should be replaced with "http://api.pubmatic.com/v1/inventory/".
HTTP MethodPUT

Request Headers

                 

Header Name
Type
Value
Required
Description
Authorization
String
Bearer ${access_token}
Yes
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

Path Parameters

               
Parameter Name
Type
Required
Description
id
Long
Yes
ID of the targeting whose details need to be updated.
For example, 123

Request Body

                                                                                                                                                                                  

Body Parameter

Type

Required

Validations

Description

name

String

No

  • Maximum length is 250 characters
  • Name should be unique for your account
  • Unsupported characters are |!{}[]^"~*?:;+\

Name of the targeting

description

String

No

  • Maximum length is 250 characters
  • Unsupported characters are |!{}[]^"~*?:;+\

Description of the targeting

geos

JSON Array of Integer

No

Value should already exist in the system

Geos to be associated with the targeting

For example, US, Canada, New York

zips

JSON Array of Integer

No

 

Zips to be associated with the targeting For example, 453216

audienceSegments

JSON Array of Integer

No

Value should already exist in the system
 

Custom audience segments to be associated with the targeting

pixel (Inclusion/Exclusion)

JSON Array of Integer

No

Value should already exist in the system

Targeting/Re-targeting pixels to be included in the targeting (pixel.includes) and/or excluded from the targeting (pixel.excludes)

daysOfWeek

JSON Array of Integer

No

Value should already exist in the system

Days of the week on which the targeting will be applicable

startTimeParting

Timestamp

No

HH:MM:SS

Time of the day from which the targeting will be applicable

endTimeParting

Timestamp

No

HH:MM:SS

Time of the day till which the targeting will be applicable

Browsers

JSON Array of Integer

No

Value should already exist in the system

Browsers to be associated with the targeting

For example, IE, Firefox, etc.

connectionTypes

JSON Array of Integer

No

Value should already exist in the system

Connection types to be associated with the targeting

For example, Cellular, Dialup, etc.

osTypes

JSON Array of Integer

No

Value should already exist in the system

OS types to be associated with the targeting

For example, iOS, Android, etc.

os

JSON Array of Integer

No

Value should already exist in the system

IDs of the OSs to be associated with the targeting

carriers

JSON Array of Integer

No

Value should already exist in the system
 

Mobile carriers to be associated with the targeting

latLong

Boolean

No

Should be a valid Boolean value

Indicates whether latitude/longitude targeting should be enabled in the targeting or not.

deviceIdType

Integer

No

Value should already exist in the system

Types of device IDs to be associated with the targeting. Possible options are:

  • 1 - IDFA
  • 3 - Android ID

videoAdTypes

JSON Array of Integer

No

Value should already exist in the system

Types of video ads to be associated with the targeting

For example, Linear, Non-Linear, etc.

videoAdPositions

JSON Array of Integer

No

Value should already exist in the system

Video ad positions to be associated with the targeting

For example, Pre-roll, Post-roll, etc.

videoPlaybackMethods

JSON Array of Integer

No

Value should already exist in the system
 

Video Playback methods to be associated with the targeting

For example, 'Auto-play sound on', Click-to-play, etc.

preset

Boolean

No

Should be a valid Boolean value

Indicates whether the targeting should be saved as a preset for future use or not.

richMediaTechnologies

JSON Array of Integer

No

Value should already exist in the system

Rich Media Technologies for Targeting
e.g.  Eyeblaster, Pointroll

matchedUsers

Boolean

No

Should be a valid boolean value

Indicates whether cookies are placed on visitoräó»s browser or not

smartphones

JSON Array of Integer

No

Value should already exist in the system

Smart phone devices for targeting

For example, Smart Phone

tablets

JSON Array of Integer

No

Value should already exist in the system

Tablet devices for targeting

For example, Tablet

Sample Request

 

 

PUT $URI_PREFIX/targeting/123

 

 

{
    "name": "test_for_targeting",
    "description": "test description for Targeting",
    "geos": [
        5,
        6
    ],
    "audienceSegments": [
        1,
        2
    ],
    "pixel": {
        "includes": [
            3
        ],
        "excludes": [
            4
        ]
    },
    "daysOfWeek": [
        1,
        2,
        3,
        4,
        5,
        6,
        7
    ],
    "startTimeParting": "00:00:00",
    "endTimeParting": "08:00:00",
    "browsers": [
        4
    ],
    "connectionTypes": [
        4
    ],
    "os": [
        10
    ],
    "osTypes": [
        2
    ],
    "smartphones": [
        575
    ],
    "tablets": [
        94,
        96
    ],
    "carriers": [
        309
    ],
    "latLong": false,
    "deviceIdType": [
        1
    ],
    "videoAdTypes": [
        1
    ],
    "videoAdPositions": [
        2
    ],
    "videoPlaybackMethods": [
        3
    ],
    "preset": true,
    "richMediaTechnologies": [
        1
    ],
    "matchedUsers": true
}

Response

Response Body

           

Type
Description
Targeting object
JSON response of the successfully-updated targeting unit

Sample Response:


{
    "id": 123,
    "name": "test_for_targeting",
    "description": "test description for Targeting",
    "geos": [
        {
            "id": 5,
            "name": "Afghanistan",
            "uri": "$URI_PREFIX/common/geo/5",
            "geoLevel": "COUNTRY"
        },
        {
            "id": 6,
            "name": "Antigua and Barbuda",
            "uri": "$URI_PREFIX/common/geo/6",
            "geoLevel": "COUNTRY"
        }
    ],
    "audienceSegments": [
        {
            "id": 1,
            "name": "Students",
            "uri": "$URI_PREFIX/audiences/1"
        },
        {
            "id": 2,
            "name": "Auto",
            "uri": "$URI_PREFIX/audiences/2"
        }
    ],
    "pixel": {
        "includes": [
            {
                "id": 3,
                "name": "TestPixel"
            }
        ],
        "excludes": [
            {
                "id": 4,
                "name": "TestPixel1"
            }
        ]
    },
    "daysOfWeek": [
        {
            "id": 7,
            "name": "SUNDAY"
        },
        {
            "id": 6,
            "name": "SATURDAY"
        },
        {
            "id": 5,
            "name": "FRIDAY"
        },
        {
            "id": 4,
            "name": "THURSDAY"
        },
        {
            "id": 3,
            "name": "WEDNESDAY"
        },
        {
            "id": 2,
            "name": "TUESDAY"
        },
        {
            "id": 1,
            "name": "MONDAY"
        }
    ],
    "startTimeParting": "00:00:00",
    "endTimeParting": "08:00:00",
    "browsers": [
        {
            "id": 4,
            "name": "Opera",
            "uri": "$URI_PREFIX/common/browser/4"
        }
    ],
    "connectionTypes": [
        {
            "id": 4,
            "name": "Dialup"
        }
    ],
    "osTypes": [
        {
            "id": 2,
            "name": "Android"
        }
    ],
    "os": [
        {
            "id": 10,
            "name": "Android 1",
            "uri": "http://172.16.4.66:8080/common/mobileOS/10"
        }
    ],
    "carriers": [
        {
            "id": 309,
            "name": "Three",
            "uri": "http://172.16.4.66:8080/common/mobileCarrier/309"
        }
    ],
    "latLong": false,
    "deviceIdType": [
        {
            "id": 1,
            "name": "IDFA"
        }
    ],
    "videoAdTypes": [
        {
            "id": 1,
            "name": "Linear"
        }
    ],
    "videoAdPositions": [
        {
            "id": 1,
            "name": "Pre-roll"
        }
    ],
    "videoPlaybackMethods": [
        {
            "id": 3,
            "name": "Click-to-play"
        }
    ],
    "preset": true,
    "creationTime": "2014-09-24T21:46:42Z",
    "modificationTime": "2014-10-07T17:55:35Z",
    "deleted": false,
    "richMediaTechnologies": [
        {
            "id": 1,
            "name": "Pointroll",
            "uri": "$URI_PREFIX/common/richMediaTechnology/1"
        }
    ],
    "matchedUsers": true,
    "smartphones": [
        {
            "id": 575,
            "name": "Nokia All Other Smart Phones"
        }
    ],
    "tablets": [
        {
            "id": 94,
            "name": "Sony Tablet S"
        },
        {
            "id": 96,
            "name": "HP Touch Pad"
        }
    ]
}

Error Codes

                                                                                                                                                              

Error code
Description
TU_001_0001Invalid targeting unit ID.
TU_001_0002Invalid user ID.
TU_001_0003Name cannot exceed 255 characters.
TU_001_0004Description cannot exceed 512 characters.
TU_001_0005Invalid or null value for Owner Type field.
TU_001_0006Invalid owner ID.
TU_001_0008Error in validating publisher info.
TU_001_0009Invalid or null value for Owner Type field.
TU_001_0010Invalid Audience Segments selected.
TU_001_0011Invalid Geos selected.
TU_001_0012Internal error in validating selected Geos.
TU_001_0013Invalid Browser IDs passed.
TU_001_0014Invalid Mobile OS IDs passed.
TU_001_0016Invalid Connection type IDs passed.
TU_001_0018Invalid Mobile Carrier IDs passed.
TU_001_0019Invalid Phone Type IDs passed.
TU_001_0020Invalid Video Playback Method IDs passed.
TU_001_0021Invalid Video Position IDs passed.
TU_001_0022Invalid Mobile OS type IDs passed.
TU_001_0023Invalid Geo IDs passed.
TU_001_0025Invalid Video Type IDs passed.
TU_001_0026Invalid Resource Type found for logged in user.
TU_001_0027Mobile OS IDs are not mapped to Mobile OS Type IDs.
TU_001_0029Invalid Days Of Week IDs passed.
TU_001_0030Invalid Device ID Types passed.
TU_001_0031Targeting creation failed.
TU_001_0032End time parting cannot be before start time parting.
TU_001_0033Targeting name already exists. Please use another name.
TU_001_0034Demand Partner/ATD not supported
TU_001_0035Invalid Targeting name. Following characters are not allowed : |!{}[]^"~*?:;+\
TU_001_0036Invalid Targeting description. Following characters are not allowed : |!{}[]^"~*?:;+\
TU_001_0037Invalid Pixels passed.
TU_001_0038Targeting name cannot be null, if preset is set to true.
TU_001_0039No targeting found for given targeting ID.
TU_001_0040Error in fetching targeting details.
TU_001_0041User does not have access to update targeting.
TU_001_0046Targeting cannot be edited as it is already used in a transaction entity
TU_001_0045Invalid Rich Media Technology ID passed.

 

 

Deleting Targeting Details

Overview

This API allows you to delete a targeting from the PubMatic system.

Request

         
URI

$URI_PREFIX/targeting/{id}



Note: For sandbox testing, $URI_PREFIX should be replaced with "http://api-sandbox.pubmatic.com/v1/inventory".

For production, $URI_PREFIX should be replaced with "http://api.pubmatic.com/v1/inventory/".
HTTP MethodDELETE

Request Headers

                 

Header Name
Type
Value
Required
Description
Authorization
String
Bearer ${access_token}
Yes
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.

Path Parameters

               
Parameter Name
Type
Required
Description
id
Long 
Yes 
ID of the targeting which is to be deleted.
For example, 123

Sample Request JSON


DELETE $uri_prefix/targeting/123

Response

Response Body

             

Response Body Parameter
Type
Description
statusStringStatus of delete operation

Sample Response JSON

 

{
    status: "success"
}

 

Error Codes

               
Error Code
Error Description
TU_001_XXXXInvalid Targeting ID.
TU_001_YYYYCannot delete Targeting as it is already in use.

Sample error response

 

[
    {
        "errorCode": "TU_001_XXXX",
        "errorMessage": "Invalid Targeting id"
    }
]

 

Unified Ad Server References

Common Request Query Parameters for Web Services

Supported Operations for Filters

HTTP Status Codes

Unified Ad Server Specific Error Codes

Attachments

    Outcomes