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

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


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 NameRequiredDescription
accountIdConditionalID of an account on PubMatic platform. This is mandatory if account is a publisher, demand partner, etc.
accountTypeYesType of an account on PubMatic platform. Options are: PUBLISHER or DATA_PROVIDER_CLIENT.
clientIdConditionalId of an account on data provider's platform. This is mandatory if account type is DATA_PROVIDER_CLIENT.
idNoId of audience.
nameNoName of audience.
searchKeyNosearch string to be matched against name or ID of an audience.
dataProviderIdConditionalID of a data provider. This is mandatory if account type is DATA_PROVIDER_CLIENT.
providerAudienceIdNoProvider audience ID.
enabledNostate of the audience. 1: enabled, 0: disabled.
privateNo1: private audience, 0: sharable audience. Private audiences are ones which can't be shared with other accounts using PubMatic's audience platform.
baseAudienceNo1: 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

NoThis accepts multiple audience types (MY_AUDIENCE, SHARED_AUDIENCE, ALL_AUDIENCE). e.g. audienceType=MY_AUDIENCE&audienceType=SHARED_AUDIENCE
Default values is  MY_AUDIENCE
dataProviderOrganizationNameNoName of the Data Provider Organization
dataProviderOrganizationIdNoId of the Data Provider Organization
pageSizeNoMaximum number of rows to be included in the response. Its default value is 5
pageNumberNoPage number to be fetched incase of multiple pages. Its default value is 1.

Request Body

No request body is expected.

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


{
     "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


{
     "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




  • 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

Description

name

NoMandatory and length <= 256

description

Nolength <= 1024

enabled

No

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

accountId

Conditional

Mandatory 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

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

dataProviderId

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

clientId

ConditionalMandatory if accountType is DATA_PROVIDER_CLIENT.

transferCode

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


{
    "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.


{
	"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


{
    "accountId":27332341,
    "accountType":"PUBLISHER",
    "name":"Travel Enthusiasts updated",
    "description":"test",
    "dataProviderId":"383",
    "transferCode":"14232323",
    "price":"1.0"
}


{
	"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


{
    "accountId":27332341,
    "accountType":"PUBLISHER",
    "name":"Travel Enthusiasts updated",
    "description":"test",
    "dataProviderId":"3834",
    "transferCode":"14232323",
    "price":"1.0"
}


[
       {
           "errorCode": "AUD01_0005",
           "errorMessage": "Please provide a valid data provider ID."
       }
]



There are two ways to register a new audience 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


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

Mandatory and length <= 256

description

No


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

length <= 1024

definition

Conditional


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.

length <= 1024

enabled

No


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

private

No


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

accountId

Conditional


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

Mandatory if accountType is PUBLISHER/DEMAND_PARTNER/BUYER.

accountType

Yes


This is a type of account on PubMatic's platform.

Mandatory and can be:

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

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


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

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

providerAudienceId

Conditional


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

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

clientId

Conditional


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

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

queryInfix

Conditional


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

price

No


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

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

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.

{
    "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.

{
    "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


{
	"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


{
    "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:

{
	"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


{
    "accountId":27332341,
    "accountTypeId":"PUBLISHER",
    "name":"Travel Enthusiasts",
    "description":"test",
    "queryInfix":"(,383:216804,AND,383:223315,AND,383:183659,AND,383:183663,)"
}

Response:

{
       "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


{
    "accountId":27332341,
    "accountTypeId":"PUBLISHER",
    "name":"Travel Enthusiasts",
    "description":"test",
    "queryInfix":"(,383:216804393,AND,383:223315,AND,383:183659,AND,383:183663,)"
}

Response:

[
       {
           "errorCode": "AUD01_0034",
           "errorMessage": "Query validation failed."
       }
]



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

  • 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

Description

idYesThe PubMatic Audience ID
nameNoMandatory and length <= 256
descriptionNolength <= 1024
enabledNoValue should be 0 or 1. otherwise defaulted to 1.
accountIdConditional

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

Mandatory if accountType is PUBLISHER.

accountTypeYesMandatory and among PUBLISHER, and DATA_PROVIDER_CLIENT
enabledForAIMTagNoIf 1, and if AIM Tag is already available for this account, this audience would be sent in response to corresponding AIM Tag call.
dataProviderIdYesId of data provider on PubMatic platform for which the audience is being created.
clientIdConditionalMandatory if accountType is DATA_PROVIDER_CLIENT.
transferCodeNoFor 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.
priceNo

The price to which the audience should be updated.

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


[
    {
        "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.


[
    {
        "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


[
	{
            "id": 23900,
			"name":"Travel Enthusiasts updated",
            "accountId": 114634,
            "accountType": "PUBLISHER",
		    "dataProviderId":"383",
            "enabled": 0
	}
]

Response:

[
	{
		"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


[
	{
	    "id": 475332,    
    	"accountId":27332341,
	    "accountType":"PUBLISHER",
	    "name":"Travel Enthusiasts updated",
    	"description":"test",
	    "dataProviderId":"3834",
    	"transferCode":"14232323",
	    "price":"1.0"
	}
}


[
       {
           "errorCode": "AUD01_0005",
           "errorMessage": "Please provide a valid data provider ID."
       }
]



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 NameRequiredDescription
accountIdConditionalID of an account on PubMatic platform. This is mandatory if account is Publisher, Demand partner etc. i.e. PubMatic account.
accountTypeYesType of an account on PubMatic platform. It can be PUBLISHER OR DATA_PROVIDER_CLIENT.
clientIdConditionalID of an account on data provider's platform. This is mandatory if account type is DATA_PROVIDER_CLIENT.
dataProviderIdConditionalID 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.


{
	"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


{
	"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:

{
	"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:

[
	{
        "errorCode": "AUD01_0036",
        "errorMessage": "Please provide a valid account ID."
	}
]



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 NameRequiredDescription

 accountId

 Yes PubMatic account ID

Response

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

Response Body

Header nameDescription

Data Provider ID

Mandatory

PubMatic Audience ID

Leave blank for Create

Source Audience ID

Mandatory

Audience 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 Audience ID

Leave blank for Create

Source Audience ID

Mandatory

Audience 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)



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 NameRequiredDescription
accountId YesPubMatic account ID
accountTypeYesPubMatic account type

Response

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

Response Body

Header nameDescription

Data Provider ID

Mandatory

PubMatic Audience ID

Leave blank for Create

Source Audience ID

Mandatory

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

http://${uri-prefix}/audience/audiences?accountId=31400&accountType=PUBLISHER&pageSize=100&pageNumber=1

Response:

Header name

Description

Data Provider ID

Mandatory

PubMatic Audience ID

Leave blank for Create

Source Audience ID

Mandatory

Audience 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)




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.


[
	{
        "errorCode": "AUD01_0036",
        "errorMessage": "Please provide a valid account ID."
	}
]