Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Updated URI for "Register a new audience"

...

Excerpt

The Audience API lets buyers and publishers integrate data providers with PubMatic Audiences.

Excerpt Include
ex:api token warning
ex:api token warning
nopaneltrue

Supported Operations

For production, replace ${uri-prefix} with: http://api.pubmatic.com

Single Audience operations

Link to documentationMethod PathTypeDescription
Retrieve a list of audiences

${uri-prefix}/audience/audiences

GETRetrieve a list of audiences registered under the same account on the PubMatic platform.
Retrieve audience details${uri-prefix}/audiences/{audienceId}GET

Retrieve the details for a specific audience on the PubMatic platform.

Register a new audience${uri-prefix}/v1/audience/audiencesPOSTRegister new audience segments on the PubMatic platform.
Update an audience

${uri-prefix} /audiences/{audienceId}

PATCHModify these fields for an audience on PubMatic platform: name, description, price and enabled flag.
Update multiple audiences

${uri-prefix}/audiences/bulk

PATCHModify fields for multiple audiences in a single call on the PubMatic platform.

Bulk Audience operations

Link to documentationMethod pathTypeDescription
Create audience template

${uri-prefix}/audiences/downloadCreateAudienceTemplate

GETDownload a (CSV) template to create one or more audiences.
Update audience template${uri-prefix}/audiences/downloadUpdateAudienceTemplateGETDownload a (CSV) template to update one or more audiences.
Bulk upload operation{uri_prefix}/infrastructure/bulkOperationsPOST

Perform bulk operations with supported multi-part request formats. This method submits the file to the uploader process.


Anchor
one
one

UI Expand
titleRetrieve a list of audiences

Retrieve a list of audiences registered under the same account on the PubMatic platform.

Request

For production, replace ${uri-prefix} with: http://api.pubmatic.com

URI${uri-prefix}/audiences
MethodGET

Request Headers

Header NameTypeValueRequiredDescription

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 our access tokens, see Getting Started with PubMatic APIs.

Content-TypeStringapplication/jsonYesMedia type for the request.

Request Parameters

Parameter NameRequiredValidationsDescription
accountIdConditionalYesID of an account on PubMatic platform. This is mandatory if account is a publisher, demand partner, etc.
accountTypeYesYesType of an account on PubMatic platform. Options are: PUBLISHER or DATA_PROVIDER_CLIENT.
clientIdConditionalYesId of an account on data provider's platform. This is mandatory if account type is DATA_PROVIDER_CLIENT.
idNoNoId of audience.
nameNoNoName of audience.
searchKeyNoNosearch string to be matched against name or ID of an audience.
dataProviderIdConditionalYesID of a data provider. This is mandatory if account type is DATA_PROVIDER_CLIENT.
providerAudienceIdNoNoProvider audience ID.
enabledNoNostate of the audience. 1: enabled, 0: disabled.
privateNoNo1: private audience, 0: sharable audience. Private audiences are ones which can't be shared with other accounts using PubMatic's audience platform.
baseAudienceNoNo1: base audience, 0: complex audience. Base audiences are ones with no AND/OR rule like Males, Females whereas complex audiences are ones with multiple audiences with AND/OR between them like "Males AND New York residents AND age group 20-30"

audienceType

NoYesThis accepts multiple audience types (MY_AUDIENCE, SHARED_AUDIENCE, ALL_AUDIENCE). e.g. audienceType=MY_AUDIENCE&audienceType=SHARED_AUDIENCE
Default values is  MY_AUDIENCE
dataProviderOrganizationNameNoNoName of the Data Provider Organization
dataProviderOrganizationIdNoNoId of the Data Provider Organization

Request Body

No request body is expected.

Code Block
languagetext
titleSample request URL
http://localhost:8018/audience/audiences?accountId=31400&accountType=PUBLISHER

Response

Header NameTypeValueRequiredDescription

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 on using our access tokens, see Getting Started with PubMatic APIs.

Content-TypeStringapplication/JSONYesMedia type for the request.

Response Body

Body ParameterDescription
idUnique Identifier for an audience registered on PubMatic platform.
nameName of an audience.
accountIdId of account on PubMatic platform.
accountNameName of account on PubMatic platform.
accountTypeType of an account on PubMatic platform. Response would never have DATA_PROVIDER_CLIENT as account type. This type is reserved to be used as request parameter value as data provider calling API may not have account ID of client on PubMatic's platform and so it would be passing clientId instead of accountId in request.
providerAudienceIdId of this audience on data provider's platform.
transferCodeTransfer code for an audience.
definitionRule definition of an audience. This is applicable to audiences managed by data platform and not by PubMatic.
descriptionDescription of the audience.
queryPostfixRule for this audience.
queryInfixRule for this audience.
uniqueAudiencesUnique audiences used to create this audience.
enabledThis flag defines whether this audience is enabled or not. If 0, audience won't be available for creating deals or rules.
audienceGroupIdaudience group id for this audience.
creationTime Creation time for this audience.
modificationTime Last modification time for this audience.
favourite
priceThe price associated with the audience
privateIf 1, this audience can't be shared with any other account.
dataProviderIdData Provider ID for this audience.
dataProviderNameName of the data provider.
enabledForAIMTagIf 1, this audience would be sent in response to AIM tag call.
clientIdID of this account on data provider's platform. (identified by account ID and account type on the PubMatic platform).

Examples

Example 1: Internal call where account ID is a mandatory parameter

Request:

URI${uri-prefix}/audiences?accountId=27332341&accountType=PUBLISHER
MethodGET


Code Block
languagetext
titleResponse
collapsetrue
{
     "metaData": {
        "endRecordNumber": "2",
        "startRecordNumber": "1",
        "pageSize": "2",
        "pageNumber": "1",
        "numberOfPages": "12",
        "totalRecords": "23"
     },
     "items": [{
		"id": 475332,
		"name": "Travel Enthusiasts",
		"description": "test",
		"definition": "Male AND AGE < 24 AND EDU=PHOTO",
		"enabled": 1,
		"creationTime": "2013-07-17 14:02:17",
		"modificationTime": "2013-07-17 14:02:17",
		"private": 1,
		"accountId": 27332341,
		"accountType": "PUBLISHER",
		"accountName": "Some Publisher",
		"enabledForAIMTag": 0,
		"dataProviderId": 383,
		"dataProviderName": "Some data provider",
		"providerAudienceId": "7",
		"clientId": "345343",
		"transferCode": "14232323",
		"audienceGroupId": "1",
		"queryPostfix": "383:7",
		"queryInfix": "(,383:7,)",
		"uniqueAudiences": "383:7"
	},
	{
		"id": 475333,
		"name": "Travel Enthusiasts Other",
		"description": "test something",
		"definition": "Male AND AGE < 24 AND EDU=PHOTO and some more",
		"enabled": 1,
		"creationTime": "2013-07-18 14:02:17",
		"modificationTime": "2013-07-18 14:02:17",
		"private": 1,
		"accountId": 27332341,
		"accountType": "PUBLISHER",
		"accountName": "Some Publisher",
		"enabledForAIMTag": 0,
		"dataProviderId": 383,
		"dataProviderName": "Some data provider",
		"providerAudienceId": "71",
		"clientId": "345343",
		"transferCode": "142323213",
		"audienceGroupId": "1",
		"queryPostfix": "383:71",
		"queryInfix": "(,383:71,)",
		"uniqueAudiences": "383:71"
	}]
]


Example 2: External call where client ID is mandatory

Request:

URI${uri-prefix}/audiences?clientId=345343&accountType=DATA_PROVIDER_CLIENT&dataProviderId=383
MethodGET


Code Block
languagetext
titleResponse
linenumberstrue
collapsetrue
{
     "metaData": {
        "endRecordNumber": "2",
        "startRecordNumber": "1",
        "pageSize": "2",
        "pageNumber": "1",
        "numberOfPages": "12",
        "totalRecords": "23"
     },
     "items": [{
		"id": 475332,
		"name": "Travel Enthusiasts",
		"description": "test",
		"definition": "Male AND AGE < 24 AND EDU=PHOTO",
		"enabled": 1,
		"creationTime": "2013-07-17 14:02:17",
		"modificationTime": "2013-07-17 14:02:17",
		"private": 1,
		"accountId": 27332341,
		"accountType": "PUBLISHER",
		"accountName": "Some Publisher",
		"enabledForAIMTag": 0,
		"dataProviderId": 383,
		"dataProviderName": "Some data provider",
		"providerAudienceId": "7",
		"clientId": "345343",
		"transferCode": "14232323",
		"audienceGroupId": "1",
		"queryPostfix": "383:7",
		"queryInfix": "(,383:7,)",
		"uniqueAudiences": "383:7"
	},
	{
		"id": 475333,
		"name": "Travel Enthusiasts Other",
		"description": "test something",
		"definition": "Male AND AGE < 24 AND EDU=PHOTO and some more",
		"enabled": 1,accountId=27332341
		"creationTime": "2013-07-18 14:02:17",
		"modificationTime": "2013-07-18 14:02:17",
		"private": 1,
		"accountId": 27332341,
		"accountType": "PUBLISHER",
		"accountName": "Some Publisher",
		"enabledForAIMTag": 0,
		"dataProviderId": 383,
		"dataProviderName": "Some data provider",
		"providerAudienceId": "71",
		"clientId": "345343",
		"transferCode": "142323213",
		"audienceGroupId": "1",
		"queryPostfix": "383:71",
		"queryInfix": "(,383:71,)",
		"uniqueAudiences": "383:71"
	}]
]



Example 3: Call with invalid request parameters.

Request:

URI${uri-prefix}/audiences?accountType=PUBLISHER
MethodGET



Anchor
two
two

UI Expand
titleUpdate an audience


Info
titleBefore you begin:
  • This method can be used to modify: name, description, price, and enabled flag. Clients can pass any of these four fields along with all mandatory parameters.
  • Do not use this API to modify complex audiences that were created with audiences of more than one data provider. These audiences are immutable and can't be updated due to access control restrictions.

Request

For production, replace ${uri-prefix} with: http://api.pubmatic.com

URI${uri-prefix}/audiences/{audienceId}
MethodPATCH

Request Headers

Header NameTypeValueRequiredDescription

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, see Getting Started with PubMatic APIs.

Content-TypeStringapplication/JSONYesMedia type for the request.

Request Body

Body Parameter

Required

Validations

Description

name

NoMandatory and length <= 256

description

Nolength <= 1024

enabled

NoValue should be 0 or 1. otherwise defaulted to 1.In case of no value or invalid value, defaulted to 1.

accountId

ConditionalMandatory if accountType is PUBLISHER.Publisher ID should be passed against this field in account type is PUBLISHER.

accountType

Yes

Mandatory and among PUBLISHER, and DATA_PROVIDER_CLIENT


enabledForAIMTag

No
If 1, and if AIM Tag is already available for this account, this audience would be sent in response to corresponding AIM Tag call.

dataProviderId

Yes


Id of data provider on PubMatic platform for which the audience is being created.

clientId

ConditionalMandatory if accountType is DATA_PROVIDER_CLIENT.

transferCode

No
For most of the data providers, this is same as provider audience id. If different, it has to be passed explicitly else defaulted to provider audience id value.

price

NoValue should be greater than or equal to 0 else it will be defaulted to 0.the price to which the audience should be updated to.


Code Block
languagetext
titleSample Request JSON
collapsetrue
{
    "accountId":27332341,
    "accountType":"PUBLISHER",
    "name":"Travel Enthusiasts",
    "description":"test",
    "dataProviderId":"383",
    "transferCode":"14232323",
    "price":"1.0"
}

Response

Header NameTypeValueRequiredDescription

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, see Getting Started with PubMatic APIs.

Content-TypeStringapplication/JSONYesMedia type for the request.

Response Body

Body Parameter

Description

id

Unique Identifier for an audience registered on PubMatic platform.

name

Name of the audience.

description

Description of the audience.

definition

Rule definition of an audience. This is applicable to audiences managed by data platform and not by PubMatic.

enabled

This flag defines whether this audience is enabled or not. If 0, audience won't be available for creating deals or rules.

private

If 1, this audience can't be shared with any other account.

accountId

Id of account on PubMatic platform.

accountType

Type of an account on PubMatic platform.

accountName

Name of account on PubMatic platform.

enabledForAIMTag

If 1, this audience would be sent in response to AIM tag call.

dataProviderId

Data Provider Id for this audience.

dataProviderName

Name of the data provider.

providerAudienceId

Id of this audience on data provider's platform.

clientId

Id of this account on data provider's platform. (identified by account Id and account type on PubMatic platform).

transferCode

Transfer code for an audience.

audienceGroupId

audience group id for this audience.

queryPostfix


queryInfix

Rule for this audience.

uniqueAudiences

Unique audiences used to create this audience.

creationTime

 Creation time for this audience.

modificationTime

 Last modification time for this audience.

price

The price to which the audience is updated.


Code Block
languagetext
titleSample Response JSON
collapsetrue
{
	"id": 475332,
	"name": "Travel Enthusiasts",
	"description": "test",
	"definition": "Male AND AGE < 24 AND EDU=PHOTO",
	"enabled": 1,
	"creationTime": "2013-07-17 14:02:17",
	"modificationTime": "2013-07-17 14:02:17",
	"private": 1,
	"accountId": 27332341,
	"accountType": "PUBLISHER",
	"accountName": "Some Publisher",
	"enabledForAIMTag": 0,
	"dataProviderId": 383,
	"dataProviderName": "Some data provider",
	"providerAudienceId": "7",
	"clientId": "345343",
	"transferCode": "14232323",
	"audienceGroupId": "1",
	"queryPostfix": "383:7",
	"queryInfix": "(383:7)",
	"uniqueAudiences": "383:7",
	"price":"1.0"
}

Examples

Example 1: Valid request to update name of an audience.

Request:

URI ${uri-prefix}/audiences/475332
MethodPATCH


Code Block
languagetext
titleSample request
collapsetrue
{
    "accountId":27332341,
    "accountType":"PUBLISHER",
    "name":"Travel Enthusiasts updated",
    "description":"test",
    "dataProviderId":"383",
    "transferCode":"14232323",
    "price":"1.0"
}


Code Block
languagetext
titleSample response
collapsetrue
{
	"id": 475332,
	"name": "Travel Enthusiasts updated",
	"description": "test",
	"definition": "Male AND AGE < 24 AND EDU=PHOTO",
	"enabled": 1,
	"creationTime": "2013-07-17 14:02:17",
	"modificationTime": "2013-07-17 14:02:17",
	"private": 1,
	"accountId": 27332341,
	"accountType": "PUBLISHER",
	"accountName": "Some Publisher",
	"enabledForAIMTag": 0,
	"dataProviderId": 383,
	"dataProviderName": "Some data provider",
	"providerAudienceId": "7",
	"clientId": "345343",
	"transferCode": "14232323",
	"audienceGroupId": "1",
	"queryPostfix": "383:7",
	"queryInfix": "(383:7)",
	"uniqueAudiences": "383:7",
	"price":"1.0"
}


Example 2: A request with incorrect data provider ID

Request:

URI ${uri-prefix}/audiences/475332
MethodPATCH


Code Block
languagetext
titleSample request
collapsetrue
{
    "accountId":27332341,
    "accountType":"PUBLISHER",
    "name":"Travel Enthusiasts updated",
    "description":"test",
    "dataProviderId":"3834",
    "transferCode":"14232323",
    "price":"1.0"
}


Code Block
languagetext
titleSample response
collapsetrue
[
       {
           "errorCode": "AUD01_0005",
           "errorMessage": "Please provide a valid data provider ID."
       }
]



Anchor
three
three

UI Expand
titleRegister a new audience

There are two ways to register a new audience segment in the PubMatic system:

  • First-party data providers (DMPs) and data provider accounts who integrate directly with PubMatic: DMPs can register audiences by providing accountType parameter as PUBLISHER, DEMAND_PARTNER, or BUYER, and the corresponding accountId that's present in PubMatic system. For data provider accounts, the accountType should be BUYER.

OR

  • For third party clients who have their own account ID in the PubMatic system, but are integrated with a third-party platform that's integrated with PubMatic: These accounts are assigned a clientId and should use the accountType parameter of DATA_PROVIDER_CLIENT (note that this refers to custom integrations and not second-party data providers). In this case, the clientId parameter will be the dataProviderId in order to identify the publisher/buyer/DSP. NOTE: If you want to use clientId to create an audience, please inform the Audience Ops team before creating a DPID in PubMatic system.

Request

URI${uri-prefix}/v1/audience/audiences
MethodPOST

Request Headers

Header NameTypeValueRequiredDescription

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, see Getting Started with PubMatic APIs.

Content-TypeStringapplication/jsonYesMedia type for the request.

Request Body

Body Parameter

Required

Validations

Description

name

Yes

Mandatory and length <= 256

The name of the new audience segment; for example, "Automobile Buyers".

description

No

length <= 1024

An optional description of the purpose, target, and any other relevant information about this audience segment.

definition

Conditional

length <= 1024

This is the rule at data provider's platform for this audience. Doesn't have any meaning on PubMatic platform other than textual representation of audience rule.

enabled

No

Value should be 0 or 1. otherwise defaulted to 1.

In case of no value or invalid value, defaulted to 1.

private

No

Value should be 0 or 1. otherwise defaulted to 1.

In case of no value or invalid value, defaulted to 1.

accountId

Conditional

Mandatory if accountType is PUBLISHER/DEMAND_PARTNER/BUYER.

Publisher ID/ Buyer Id /DSP ID should be passed against this field in account type is PUBLISHER/BUYER/DEMAND_PARTNER respectively

accountType

Yes

Mandatory and can be:

  • PUBLISHER, DEMAND_PARTNER, BUYER
  • DATA_PROVIDER_CLIENT (do not use for Audience Encore)

It is type of account on PubMatic's platform.

Note: Response would never have DATA_PROVIDER_CLIENT as account type. This is because a data provider calling the API may not have the account ID of a client on PubMatic's platform, so it would be passing clientId instead of accountId in request.

enabledForAIMTag

No


If 1, and if AIM Tag is already available for this account, this audience would be sent in response to corresponding AIM Tag call.

dataProviderId

Conditional

Mandatory if audience being created is not a complex audience. i.e. audience with AND/OR between multiple audiences.

Id of data provider on PubMatic platform for which the audience is being created.

providerAudienceId

Conditional

Mandatory if audience being created is not a complex audience. i.e. audience with AND/OR between multiple audiences.

ID of this audience in the data provider's system.

clientId

Conditional

Mandatory if accountType is DATA_PROVIDER_CLIENT.

ID of the account in the data provider's system to which the audience belongs (identified by the account ID and account type in the PubMatic system).

transferCode

No


For most of the data providers, this is same as provider audience id. If different, it has to be passed explicitly else defaulted to provider audience id value.

queryInfix

Conditional

Mandatory if audience being created is a complex audience. i.e. audience with AND/OR between multiple audiences.


price

No

Value should be greater than or equal to 0 else it will be defaulted to 0.

If any entity (Publisher, DSP or Buyer) wants to sell their audience, this param specifies the price associated with it.

Sample JSON

There are two JSON request payload this API works with. The payload is determines by whether it is a simple audience without a complex rule, or a complex audience with multiple simple audiences used with AND/OD between them.

Sample 1: Registration of a simple audience.

Code Block
languagetext
titleSample JSON request
collapsetrue
{
    "accountId":27332341,
    "accountType":"PUBLISHER",
    "name":"Travel Enthusiasts",
    "description":"test",
    "dataProviderId":"383",
    "definition":"Male AND AGE < 24 AND EDU=PHOTO",
    "providerAudienceId":"7",
    "transferCode":"14232323",
    "price":"1.0"
}


Sample 2: Registration of a complex audience. A validation of queryInfix is performed to check if all base audiences are already registered on PubMatic platform.

Code Block
languagetext
titleSample JSON request
collapsetrue
{
    "accountId":27332341,
    "accountTypeId":"PUBLISHER",
    "name":"Travel Enthusiasts",
    "description":"test",
    "queryInfix":"(,383:216804,AND,383:223315,AND,383:183659,AND,383:183663,)"
}

Response

Header NameTypeValueRequiredDescription
Content-TypeStringapplication/JSONYesMedia type for the request.

Response Body

Response Body Parameter

Description

idUnique Identifier for an audience registered on PubMatic platform.
nameName of the audience.
descriptionDescription of the audience.
definitionRule definition of an audience. This is applicable to audiences managed by data platform and not by PubMatic.
enabledThis flag defines whether this audience is enabled or not. If 0, audience won't be available for creating deals or rules.
privateIf 1, this audience can't be shared with any other account.
accountIdId of account on PubMatic platform.
accountType

Type of an account on PubMatic platform.

Note: Response would never have DATA_PROVIDER_CLIENT as account type. This is because a data provider calling the API may not have the account ID of a client on PubMatic's platform, so it would be passing clientId instead of accountId in request.

accountNameName of account on PubMatic platform.
enabledForAIMTagIf 1, this audience would be sent in response to AIM tag call.
dataProviderIdData Provider Id for this audience.
dataProviderNameName of the data provider.
providerAudienceIdId of this audience on data provider's platform.
clientIdId of this account on data provider's platform. (identified by account Id and account type on PubMatic platform).
transferCodeTransfer code for an audience.
audienceGroupIdaudience group id for this audience.
queryPostfixpostfix of the rule for this audience.
queryInfixRule for this audience.
uniqueAudiencesUnique audiences used to create this audience.
creationTime Creation time for this audience.
modificationTime Last modification time for this audience.
priceThe price associated with the audience


Code Block
languagetext
titleSample JSON
collapsetrue
{
	"id": 475332,
	"name": "Travel Enthusiasts",
	"description": "test",
	"definition": "Male AND AGE < 24 AND EDU=PHOTO",
	"enabled": 1,
	"creationTime": "2013-07-17 14:02:17",
	"modificationTime": "2013-07-17 14:02:17",
	"private": 1,
	"accountId": 27332341,
	"accountType": "PUBLISHER",
	"accountName": "Some Publisher",
	"enabledForAIMTag": 0,
	"dataProviderId": 383,
	"dataProviderName": "Some data provider",
	"providerAudienceId": "7",
	"clientId": "345343",
	"transferCode": "14232323",
	"audienceGroupId": "1",
	"queryPostfix": "383:7",
	"queryInfix": "(383:7)",
	"uniqueAudiences": "383:7",
	"price": "1.0"
}

Examples

Example 1: Creating a simple audience with no complex rule. The rule is managed by DMP, and the PubMatic platform stores its metadata.

Request:

URI${uri-prefix}/v1/audiences
MethodPOST


Code Block
languagetext
titleSample JSON request body
collapsetrue
{
    "accountId":27332341,
    "accountType":"PUBLISHER",
    "name":"Travel Enthusiasts",
    "description":"test",
    "dataProviderId":"383",
    "definition":"Male AND AGE < 24 AND EDU=PHOTO",
    "providerAudienceId":"7",
    "transferCode":"14232323",
   
    "price":"1.0"
}

Response:

Code Block
languagetext
titleSample JSON response
collapsetrue
{
	"id": 475332,
	"name": "Travel Enthusiasts",
	"description": "test",
	"definition": "Male AND AGE < 24 AND EDU=PHOTO",
	"enabled": 1,
	"creationTime": "2013-07-17 14:02:17",
	"modificationTime": "2013-07-17 14:02:17",
	"private": 1,
	"accountId": 27332341,
	"accountType": "PUBLISHER",
	"accountName": "Some Publisher",
	"enabledForAIMTag": 0,
	"dataProviderId": 383,
	"dataProviderName": "Some data provider",
	"providerAudienceId": "7",
	"clientId": "345343",
	"transferCode": "14232323",
	"audienceGroupId": "1",
	"queryPostfix": "383:7",
	"queryInfix": "(383:7)",
	"uniqueAudiences": "383:7",
	"price":"1.0"
}


E xample 2: Creating a complex audience. 

Request:

URI${uri-prefix}/v1/audiences
MethodPOST


Code Block
languagetext
titleSample JSON request body
collapsetrue
{
    "accountId":27332341,
    "accountTypeId":"PUBLISHER",
    "name":"Travel Enthusiasts",
    "description":"test",
    "queryInfix":"(,383:216804,AND,383:223315,AND,383:183659,AND,383:183663,)"
}

Response:

Code Block
languagetext
titleSample JSON response
collapsetrue
{
       "id": 2848,
       "name": "test rest 78",
       "longName": "test rest 78",
       "accountId": 27332341,
       "accountName": "pubAcct1, Inc.",
       "accountTypeId": 4,
       "definition": "( DP1:pubAcct1 - Private --> pubAcct1 US --> Age Range --> 18-21 AND DP1:pubAcct1 - Private --> pubAcct1 US --> Buyer Type --> Reactivated Buyer AND DP1:pubAcct1 - Private --> pubAcct1 US --> Cameras & Photo --> Film Photography AND DP1:pubAcct1 - Private --> pubAcct1 US --> Cameras & Photo --> Lenses & Filters ) ",
       "queryInfix": "(,383:216804,AND,383:223315,AND,383:183659,AND,383:183663,)",
       "enabled": 1,
       "audienceGroupId": 1,
       "creationTime": "2014-02-26 14:02:28",
       "modificationTime": "2014-02-26 14:02:28",
       "enabledForAIMTag": 0,
       "private": 1,
       "dataProviderId": "383",
       "dataProviderName": "DP1"
    }


Example 3: Creating complex audience with an invalid base audience in rule.

Request:

URI${uri-prefix}/v1/audiences
MethodPOST


Code Block
languagetext
titleSample JSON request body
collapsetrue
{
    "accountId":27332341,
    "accountTypeId":"PUBLISHER",
    "name":"Travel Enthusiasts",
    "description":"test",
    "queryInfix":"(,383:216804393,AND,383:223315,AND,383:183659,AND,383:183663,)"
}

Response:

Code Block
languagetext
titleSample response
collapsetrue
[
       {
           "errorCode": "AUD01_0034",
           "errorMessage": "Query validation failed."
       }
]



Anchor
four
four

UI Expand
titleUpdate multiple audiences

Modify fields for multiple audiences in a single call on the PubMatic platform.

Info
titleBefore you begin:
  • This method will modify these fields: name, description, price, and enabled flag. Clients can pass any of these four fields along with all mandatory parameters.
  • Do not use this method to modify complex audiences that were created with audiences of more than one data provider. These audiences are immutable and can't be updated due to access control restrictions.

Request

URI${uri-prefix}/audiences/bulk
MethodPATCH

Request Headers

Header NameTypeValueRequiredDescription

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, see Getting Started with PubMatic APIs.

Content-TypeStringapplication/jsonYesMedia type for the request.

Request Parameters

No request parameters are expected.

Request Body

Body Parameter

Required

Validations

Description

idYes
The PubMatic Audience ID
nameNoMandatory and length <= 256
descriptionNolength <= 1024
enabledNoValue should be 0 or 1. otherwise defaulted to 1.In case of no value or invalid value, defaulted to 1.
accountIdConditionalMandatory if accountType is PUBLISHER.Publisher ID should be passed against this field in account type is PUBLISHER.
accountTypeYesMandatory and among PUBLISHER, and DATA_PROVIDER_CLIENT
enabledForAIMTagNo
If 1, and if AIM Tag is already available for this account, this audience would be sent in response to corresponding AIM Tag call.
dataProviderIdYes


Id of data provider on PubMatic platform for which the audience is being created.
clientIdConditionalMandatory if accountType is DATA_PROVIDER_CLIENT.
transferCodeNo
For most of the data providers, this is same as provider audience id. If different, it has to be passed explicitly else defaulted to provider audience id value.
priceNoValue should be greater than or equal to 0 else it will be defaulted to 0.the price to which the audience should be updated to.


Code Block
languagetext
titleSample JSON
collapsetrue
[
    {
        "id": 23900,
        "accountId":27332341,
        "accountType":"PUBLISHER",
        "name":"Travel Enthusiasts",
        "description":"test",
        "dataProviderId":"383",
        "transferCode":"14232323",
        "price":"1.0",
        "enabled":1
    },
    {
        "id": 24040,
        "accountId":114634,
        "accountType":"PUBLISHER",
        "name":"Movie Goers",
        "description":"test",
        "dataProviderId":"12",
        "transferCode":"14232323",
        "price":"1.0",
        "enabled":1
    }
]

Response

Header NameTypeValueRequiredDescription
Content-TypeStringapplication/jsonYesMedia type for the request.

Response Body

Response Body Parameter

Description

idUnique Identifier for an audience registered on PubMatic platform.
nameName of the audience.
descriptionDescription of the audience.
definitionRule definition of an audience. This is applicable to audiences managed by data platform and not by PubMatic.
enabledThis flag defines whether this audience is enabled or not. If 0, audience won't be available for creating deals or rules.
privateIf 1, this audience can't be shared with any other account.
accountIdId of account on PubMatic platform.
accountTypeType of an account on PubMatic platform.
accountNameName of account on PubMatic platform.
enabledForAIMTagIf 1, this audience would be sent in response to AIM tag call.
dataProviderIdData Provider Id for this audience.
dataProviderNameName of the data provider.
providerAudienceIdId of this audience on data provider's platform.
clientIdId of this account on data provider's platform. (identified by account Id and account type on PubMatic platform).
transferCodeTransfer code for an audience.
audienceGroupIdaudience group id for this audience.
queryPostfix
queryInfixRule for this audience.
uniqueAudiencesUnique audiences used to create this audience.
creationTime Creation time for this audience.
modificationTime Last modification time for this audience.
priceThe price to which the audience is updated.


Code Block
languagetext
titleSample JSON
collapsetrue
[
    {
        "id": 475332,
        "name": "Travel Enthusiasts",
        "description": "test",
        "definition": "Male AND AGE < 24 AND EDU=PHOTO",
        "enabled": 1,
        "creationTime": "2013-07-17 14:02:17",
        "modificationTime": "2013-07-17 14:02:17",
        "private": 1,
        "accountId": 27332341,
        "accountType": "PUBLISHER",
        "accountName": "Some Publisher",
        "enabledForAIMTag": 0,
        "dataProviderId": 383,
        "dataProviderName": "Some data provider",
        "providerAudienceId": "7",
        "clientId": "345343",
        "transferCode": "14232323",
        "audienceGroupId": "1",
        "queryPostfix": "383:7",
        "queryInfix": "(383:7)",
        "uniqueAudiences": "383:7",
        "price":"1.0"
    },
  {
        "id": 475332,
        "name": "Movie Goers",
        "description": "test",
        "definition": "Male AND AGE < 24 AND EDU=PHOTO",
        "enabled": 1,
        "creationTime": "2019-07-17 12:10:15",
        "modificationTime": "2019-07-18 14:10:15",
        "private": 1,
        "accountId": 27332341,
        "accountType": "PUBLISHER",
        "accountName": "Some Publisher",
        "enabledForAIMTag": 0,
        "dataProviderId": 383,
        "dataProviderName": "Some data provider",
        "providerAudienceId": "7",
        "clientId": "345343",
        "transferCode": "14232323",
        "audienceGroupId": "1",
        "dataTypeId": "-1",
        "queryPostfix": "383:7",
        "queryInfix": "(383:7)",
        "uniqueAudiences": "383:7",
        "price":"1.0"
     }
]

Examples

Example 1: Valid request to update name of an audience.

URI${uri-prefix}/audiences/bulk
MethodPATCH


Code Block
languagetext
titleSample JSON request
collapsetrue
[
	{
            "id": 23900,
			"name":"Travel Enthusiasts updated",
            "accountId": 114634,
            "accountType": "PUBLISHER",
		    "dataProviderId":"383",
            "enabled": 0
	}
]

Response:

Code Block
languagetext
titleSample response
collapsetrue
[
	{
		"id": 23900,
		"name": "Travel Enthusiasts updated",
		"description": "test",
		"definition": "Male AND AGE < 24 AND EDU=PHOTO",
		"enabled": 1,
		"creationTime": "2013-07-17 14:02:17",
		"modificationTime": "2013-07-17 14:02:17",
		"private": 1,
		"accountId": 114634,
		"accountType": "PUBLISHER",
		"accountName": "Some Publisher",
		"enabledForAIMTag": 0,
		"dataProviderId": 383,
		"dataProviderName": "Some data provider",
		"providerAudienceId": "7",
		"clientId": "345343",
		"transferCode": "14232323",
		"audienceGroupId": "1",
		"queryPostfix": "383:7",
		"queryInfix": "(383:7)",
		"uniqueAudiences": "383:7",
		"price":"1.0"
	}
]


Example 2: Request with incorrect data provider ID.

URI${uri-prefix}/audiences/475332
MethodPATCH


Code Block
languagetext
titleSample JSON request
collapsetrue
[
	{
	    "id": 475332,    
    	"accountId":27332341,
	    "accountType":"PUBLISHER",
	    "name":"Travel Enthusiasts updated",
    	"description":"test",
	    "dataProviderId":"3834",
    	"transferCode":"14232323",
	    "price":"1.0"
	}
}


Code Block
languagetext
titleSample response
collapsetrue
[
       {
           "errorCode": "AUD01_0005",
           "errorMessage": "Please provide a valid data provider ID."
       }
]



Anchor
five
five

UI Expand
titleRetrieve audience details

Retrieve the details for a specific audience on the PubMatic platform.

Request

For production, replace ${uri-prefix} with: http://api.pubmatic.com

URI${uri-prefix}/audiences/{audienceId}
MethodGET

Request Header

Header NameTypeValueRequiredDescription

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, see Getting Started with PubMatic APIs.

Content-TypeStringapplication/jsonYesMedia type for the request.

Request Parameters

Parameter NameRequiredValidationsDescription
accountIdConditionalYesID of an account on PubMatic platform. This is mandatory if account is Publisher, Demand partner etc. i.e. PubMatic account.
accountTypeYesYesType of an account on PubMatic platform. It can be PUBLISHER OR DATA_PROVIDER_CLIENT.
clientIdConditionalYesID of an account on data provider's platform. This is mandatory if account type is DATA_PROVIDER_CLIENT.
dataProviderIdConditionalYesID of data provider on PubMatic platform. This is mandatory if account type is DATA_PROVIDER_CLIENT.

Response

Header NameTypeValueRequiredDescription
Content-TypeStringapplication/jsonYesMedia type for the request.

Response Body

Response Body ParameterDescription

id

Unique Identifier for an audience registered on PubMatic platform.

name

Name of the audience.

description

Description of the audience.

definition

Rule definition of an audience. This is applicable to audiences managed by data platform and not by PubMatic.

enabled

This flag defines whether this audience is enabled or not. If 0, audience won't be available for creating deals or rules.

private

If 1, this audience can't be shared with any other account.

accountId

Id of account on PubMatic platform.

accountType

Type of an account on PubMatic platform. Response would never have DATA_PROVIDER_CLIENT as account type. This type is reserved to be used as request parameter value as data provider calling API may not have account ID of client on PubMatic's platform and so it would be passing clientId instead of accountId in request.

accountName

Name of account on PubMatic platform.

enabledForAIMTag

If 1, this audience would be sent in response to AIM tag call.

dataProviderId

Data Provider Id for this audience.

dataProviderName

Name of the data provider.

providerAudienceId

Id of this audience on data provider's platform.

clientId

Id of this account on data provider's platform. (identified by account Id and account type on PubMatic platform).

transferCode

Transfer code for an audience.

audienceGroupId

audience group id for this audience.

queryPostfix

postfix of rule for this audience.

queryInfix

Rule for this audience.

uniqueAudiences

Unique audiences used to create this audience.

creationTime

 Creation time for this audience.

modificationTime

 Last modification time for this audience.

price

The pice associated with the audience.


Code Block
languagetext
titleSample response
collapsetrue
{
	"id": 475332,
	"name": "Travel Enthusiasts",
	"description": "test",
	"definition": "Male AND AGE < 24 AND EDU=PHOTO",
	"enabled": 1,
	"creationTime": "2013-07-17 14:02:17",
	"modificationTime": "2013-07-17 14:02:17",
	"private": 1,
	"accountId": 27332341,
	"accountType": "PUBLISHER",
	"accountName": "Some Publisher",
	"enabledForAIMTag": 0,
	"dataProviderId": 383,
	"dataProviderName": "Some data provider",
	"providerAudienceId": "7",
	"clientId": "345343",
	"transferCode": "14232323",
	"audienceGroupId": "1",
	"queryPostfix": "383:7",
	"queryInfix": "(,383:7,)",
	"uniqueAudiences": "383:7",
	"price":"1.0"
}

Examples

Example 1: Internal call where account Id is mandatory parameter.

Request:

URL

${uri-prefix}/audiences/475332?accountId=27332341&accountType=PUBLISHER

MethodGET


Code Block
languagetext
titleSample response
collapsetrue
{
	"id": 475332,
	"name": "Travel Enthusiasts",
	"description": "test",
	"definition": "Male AND AGE < 24 AND EDU=PHOTO",
	"enabled": 1,
	"creationTime": "2013-07-17 14:02:17",
	"modificationTime": "2013-07-17 14:02:17",
	"private": 1,
	"accountId": 27332341,
	"accountType": "PUBLISHER",
	"accountName": "Some Publisher",
	"enabledForAIMTag": 0,
	"dataProviderId": 383,
	"dataProviderName": "Some data provider",
	"providerAudienceId": "7",
	"clientId": "345343",
	"transferCode": "14232323",
	"audienceGroupId": "1",
	"queryPostfix": "383:7",
	"queryInfix": "(,383:7,)",
	"uniqueAudiences": "383:7",
	"price":"1.0"
}

Example 2: External call where client ID is mandatory.

Request:

URL

${uri-prefix}/audiences/475332?clientId=345343&accountType=DATA_PROVIDER_CLIENT&dataProviderId=383

MethodGET

Response:

Code Block
languagetext
titleSample response
collapsetrue
{
	"id": 475332,
	"name": "Travel Enthusiasts",
	"description": "test",
	"definition": "Male AND AGE < 24 AND EDU=PHOTO",
	"enabled": 1,
	"creationTime": "2013-07-17 14:02:17",
	"modificationTime": "2013-07-17 14:02:17",
	"private": 1,
	"accountId": 27332341,
	"accountType": "PUBLISHER",
	"accountName": "Some Publisher",
	"enabledForAIMTag": 0,
	"dataProviderId": 383,
	"dataProviderName": "Some data provider",
	"providerAudienceId": "7",
	"clientId": "345343",
	"transferCode": "14232323",
	"audienceGroupId": "1",
	"queryPostfix": "383:7",
	"queryInfix": "(,383:7,)",
	"uniqueAudiences": "383:7"
}

Example 3: Call with invalid request parameters.

Request:

URL${uri-prefix}/audiences/162534?accountType=PUBLISHER
MethodGET

Response:

Code Block
languagetext
titleSample response
collapsetrue
[
	{
        "errorCode": "AUD01_0036",
        "errorMessage": "Please provide a valid account ID."
	}
]



Anchor
six
six

UI Expand
titleCreate audience template

Use this API to download a (CSV file) template that enables you tocreate anaudience in bulk. Some highlights of this template:

  • The template has a row header that describes the data in each column. 
  • The file will also contain information for each of the audiences within the account. 
  • Each row represents an audience. 
  • The publisher can download this template, fill in a row for each audience to be created, and upload it in Audience UI.
  • Once uploaded, the audiences will be updated asynchronously.

Request

URI${uri-prefix}/audiences/downloadCreateAudienceTemplate
MethodGET

Request Headers

Header NameTypeValueRequiredDescription

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, see Getting Started with PubMatic APIs.

Request Parameters

Parameter NameRequiredValidationsDescription

 accountId

 Yes No PubMatic account ID

Response

Header NameTypeValueRequiredDescription
Content-TypeStringapplication/jsonYesMedia type for the request.

Response Body

Header nameValidation

Data Provider ID

Mandatory

PubMatic Segment ID

Leave blank for Create

Source Segment ID

Mandatory

Segment Name

Mandatory

PubMatic Account ID

Mandatory

Data Price

CPM in USD

Enabled?

Y/N

Source Client ID

Mandatory if account ID is blank

Comments

Displays failure reason(s)

Example

Valid request to download create audience template.

Request

URL

${uri-prefix}/audience/audiences/downloadCreateAudienceTemplate?accountId=31400

MethodGET

Response

Header nameValidation

Data Provider ID

Mandatory

PubMatic Segment ID

Leave blank for Create

Source Segment ID

Mandatory

Segment Name

Mandatory

PubMatic Account ID

Mandatory

Data Price

CPM in USD

Enabled?

Y/N

Source Client ID

Mandatory if account ID is blank

Comments

Displays failure reason(s)



Anchor
seven
seven

UI Expand
titleUpdate audience template

Use this API to download a CSV template that allows you to update audiences in bulk. Some highlight of this template:

  • The template has a row header that describes the data in each column. 
  • The file will also contain information for each of the audiences within the account. 
  • Each row represents an audience. 
  • The publisher can download this template, update the values in one or more rows, and upload it in Audience UI.
  • Once uploaded, the audiences will be updated asynchronously.

Request

URI${uri-prefix}/audiences/downloadUpdateAudienceTemplate
MethodGET

Request Headers

Header NameTypeValueRequiredDescription

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 on using our access tokens, see Getting Started with PubMatic APIs.

Request Parameters

Parameter NameRequiredValidationsDescription
accountId Yes No PubMatic account ID
accountTypeYesYesPubMatic account type

Response

Header NameTypeValueRequiredDescription
Content-TypeStringapplication/jsonYesMedia type for the request.

Response Body

Header nameValidation

Data Provider ID

Mandatory

PubMatic Segment ID

Leave blank for Create

Source Segment ID

Mandatory

Segment Name

Mandatory

PubMatic Account ID

Mandatory

Data Price

CPM in USD

Enabled?

Y/N

Source Client ID

Mandatory if account ID is blank

Comments

Displays failure reason(s)

Examples

Valid request to download update audience template.

Code Block
titleSample Request URL
collapsetrue
${uri-prefix}/audience/audiences/downloadUpdateAudienceTemplate?accountType=PUBLISHER&accountId=31400

Response:

Header name

Validation

Data Provider ID

Mandatory

PubMatic Segment ID

Leave blank for Create

Source Segment ID

Mandatory

Segment Name

Mandatory

PubMatic Account ID

Mandatory

Data Price

CPM in USD

Enabled?

Y/N

Source Client ID

Mandatory if account ID is blank

Comments

Displays failure reason(s)



UI Expand
titleError codes


Error CodeError Description
AUD01_0002Please provide a valid audience ID.
AUD01_0003Please provide an audience.
AUD01_0004Please provide a valid account ID or data provider client ID.
AUD01_0005Please provide a valid data provider ID.
AUD01_0008Please provide a valid audience name. It's length shouldn't be more than 256 characters.
AUD01_0009Please provide a valid audience description. It's length shouldn't be more than 1024 characters.
AUD01_0010Please provide a valid provider audience ID. It's length shouldn't be more than 256 characters.
AUD01_0011Please provide a valid audience definition. It's length shouldn't be more than 1024 characters.
AUD01_0012Please provide a valid transfer code. It's length shouldn't be more than 256 characters.
AUD01_0013Data Provider is not associated with Publisher.
AUD01_0014Audience already exists.
AUD01_0026Please provide a valid client ID. It's length shouldn't be more than 1024 characters.
AUD01_0031Data Provider is not associated with data provider client.
AUD01_0032Updating of Data Provider Id is not allowed.
AUD01_0034Query validation failed.
AUD01_0035Audience with same name already present. Please use different name.
AUD01_0036Please provide a valid account ID.
AUD01_0037Please provide a valid account type ID.
AUD01_0153Price cannot be negative.
AUD01_0156Active deals found.
CC03_0001No records found.


Code Block
languagetext
titleSample Error Response
linenumberstrue
collapsetrue
[
	{
        "errorCode": "AUD01_0036",
        "errorMessage": "Please provide a valid account ID."
	}
]



...