Audience API

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

Before using PubMatic APIs, first generate the API Access Token. For more information, see Getting Started with PubMatic APIs.

Supported Operations

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

Single Audience operations

Link to documentation	Method Path	Type	Description
Retrieve a list of audiences	${uri-prefix}/audience/audiences	GET	Retrieve 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/audiences	POST	Register new audience segments on the PubMatic platform.
Update an audience	${uri-prefix} /audiences/{audienceId}	PATCH	Modify these fields for an audience on PubMatic platform: name, description, price and enabled flag.
Update multiple audiences	${uri-prefix}/audiences/bulk	PATCH	Modify fields for multiple audiences in a single call on the PubMatic platform.

Bulk Audience operations

Link to documentation	Method path	Type	Description
Create audience template	${uri-prefix}/audiences/downloadCreateAudienceTemplate	GET	Download a (CSV) template to create one or more audiences.
Update audience template	${uri-prefix}/audiences/downloadUpdateAudienceTemplate	GET	Download a (CSV) template to update one or more audiences.
Bulk upload operation	{uri_prefix}/infrastructure/bulkOperations	POST	Perform bulk operations with supported multi-part request formats. This method submits the file to the uploader process.

Retrieve 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
Method	GET

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

Content-Type String application/json Yes Media type for the request.

Request Parameters

Parameter Name	Required	Validations	Description
accountId	Conditional	Yes	ID of an account on PubMatic platform. This is mandatory if account is a publisher, demand partner, etc.
accountType	Yes	Yes	Type of an account on PubMatic platform. Options are: PUBLISHER or DATA_PROVIDER_CLIENT.
clientId	Conditional	Yes	Id of an account on data provider's platform. This is mandatory if account type is DATA_PROVIDER_CLIENT.
id	No	No	Id of audience.
name	No	No	Name of audience.
searchKey	No	No	search string to be matched against name or ID of an audience.
dataProviderId	Conditional	Yes	ID of a data provider. This is mandatory if account type is DATA_PROVIDER_CLIENT.
providerAudienceId	No	No	Provider audience ID.
enabled	No	No	state of the audience. 1: enabled, 0: disabled.
private	No	No	1: private audience, 0: sharable audience. Private audiences are ones which can't be shared with other accounts using PubMatic's audience platform.
baseAudience	No	No	1: 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	No	Yes	This accepts multiple audience types (MY_AUDIENCE, SHARED_AUDIENCE, ALL_AUDIENCE). e.g. audienceType=MY_AUDIENCE&audienceType=SHARED_AUDIENCE Default values is MY_AUDIENCE
dataProviderOrganizationName	No	No	Name of the Data Provider Organization
dataProviderOrganizationId	No	No	Id of the Data Provider Organization

Request Body

No request body is expected.

Sample request URL

http://localhost:8018/audience/audiences?accountId=31400&accountType=PUBLISHER

Response

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

Content-Type String application/JSON Yes Media type for the request.

Response Body

Body Parameter	Description
id	Unique Identifier for an audience registered on PubMatic platform.
name	Name of an audience.
accountId	Id of account on PubMatic platform.
accountName	Name 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.
providerAudienceId	Id of this audience on data provider's platform.
transferCode	Transfer code for an audience.
definition	Rule definition of an audience. This is applicable to audiences managed by data platform and not by PubMatic.
description	Description of the audience.
queryPostfix	Rule for this audience.
queryInfix	Rule for this audience.
uniqueAudiences	Unique audiences used to create this audience.
enabled	This flag defines whether this audience is enabled or not. If 0, audience won't be available for creating deals or rules.
audienceGroupId	audience group id for this audience.
creationTime	Creation time for this audience.
modificationTime	Last modification time for this audience.
favourite
price	The price associated with the audience
private	If 1, this audience can't be shared with any other account.
dataProviderId	Data Provider ID for this audience.
dataProviderName	Name of the data provider.
enabledForAIMTag	If 1, this audience would be sent in response to AIM tag call.
clientId	ID 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
Method	GET

Response

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

Response

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

Update an audience

Before 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}
Method	PATCH

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

Content-Type String application/JSON Yes Media type for the request.

Request Body

Body Parameter	Required	Validations	Description
name	No	Mandatory and length <= 256
description	No	length <= 1024
enabled	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.	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	Conditional	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.
price	No	Value 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.

Sample Request JSON

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

Response

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

Content-Type String application/JSON Yes Media 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.

Sample Response JSON

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

Sample request

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

Sample response

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

Sample request

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

Sample response

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

Register 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
Method	POST

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

Content-Type String application/json Yes Media 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.

Sample JSON request

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

Sample JSON request

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

Response

Header Name	Type	Value	Required	Description
Content-Type	String	application/JSON	Yes	Media type for the request.

Response Body

Response 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. 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.
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 the 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 price associated with the audience

Sample JSON

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

Sample JSON request body

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

Sample JSON 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
Method	POST

Sample JSON request body

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

Response:

Sample JSON 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
Method	POST

Sample JSON request body

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

Response:

Sample response

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

Update multiple audiences

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

Before 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
Method	PATCH

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

Content-Type String application/json Yes Media type for the request.

Request Parameters

No request parameters are expected.

Request Body

Body Parameter	Required	Validations	Description
id	Yes		The PubMatic Audience ID
name	No	Mandatory and length <= 256
description	No	length <= 1024
enabled	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.	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	Conditional	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.
price	No	Value 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.

Sample JSON

[
    {
        "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 Name	Type	Value	Required	Description
Content-Type	String	application/json	Yes	Media type for the request.

Response Body

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

Sample JSON

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

Sample JSON request

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

Response:

Sample 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
Method	PATCH

Sample JSON request

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

Sample response

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

Retrieve 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}
Method	GET

Request Header

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

Content-Type String application/json Yes Media type for the request.

Request Parameters

Parameter Name	Required	Validations	Description
accountId	Conditional	Yes	ID of an account on PubMatic platform. This is mandatory if account is Publisher, Demand partner etc. i.e. PubMatic account.
accountType	Yes	Yes	Type of an account on PubMatic platform. It can be PUBLISHER OR DATA_PROVIDER_CLIENT.
clientId	Conditional	Yes	ID of an account on data provider's platform. This is mandatory if account type is DATA_PROVIDER_CLIENT.
dataProviderId	Conditional	Yes	ID of data provider on PubMatic platform. This is mandatory if account type is DATA_PROVIDER_CLIENT.

Response

Header Name	Type	Value	Required	Description
Content-Type	String	application/json	Yes	Media type for the request.

Response Body

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

Sample 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"
}

Examples

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

Request:

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

Sample 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"
}

Example 2: External call where client ID is mandatory.

Request:

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

Response:

Sample 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
Method	GET

Response:

Sample response

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

Create 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
Method	GET

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

Request Parameters

Parameter Name	Required	Validations	Description
accountId	Yes	No	PubMatic account ID

Response

Header Name	Type	Value	Required	Description
Content-Type	String	application/json	Yes	Media type for the request.

Response Body

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)

Example

Valid request to download create audience template.

Request

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

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)

Update 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
Method	GET

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

Request Parameters

Parameter Name	Required	Validations	Description
accountId	Yes	No	PubMatic account ID
accountType	Yes	Yes	PubMatic account type

Response

Header Name	Type	Value	Required	Description
Content-Type	String	application/json	Yes	Media type for the request.

Response Body

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)

Examples

Valid request to download update audience template.

Sample Request URL

${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)

Error codes

Error Code	Error Description
AUD01_0002	Please provide a valid audience ID.
AUD01_0003	Please provide an audience.
AUD01_0004	Please provide a valid account ID or data provider client ID.
AUD01_0005	Please provide a valid data provider ID.
AUD01_0008	Please provide a valid audience name. It's length shouldn't be more than 256 characters.
AUD01_0009	Please provide a valid audience description. It's length shouldn't be more than 1024 characters.
AUD01_0010	Please provide a valid provider audience ID. It's length shouldn't be more than 256 characters.
AUD01_0011	Please provide a valid audience definition. It's length shouldn't be more than 1024 characters.
AUD01_0012	Please provide a valid transfer code. It's length shouldn't be more than 256 characters.
AUD01_0013	Data Provider is not associated with Publisher.
AUD01_0014	Audience already exists.
AUD01_0026	Please provide a valid client ID. It's length shouldn't be more than 1024 characters.
AUD01_0031	Data Provider is not associated with data provider client.
AUD01_0032	Updating of Data Provider Id is not allowed.
AUD01_0034	Query validation failed.
AUD01_0035	Audience with same name already present. Please use different name.
AUD01_0036	Please provide a valid account ID.
AUD01_0037	Please provide a valid account type ID.
AUD01_0153	Price cannot be negative.
AUD01_0156	Active deals found.
CC03_0001	No records found.

Sample Error Response

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

Products Home

Developer Home

Resources Home

Audience API

Supported Operations

Single Audience operations

Bulk Audience operations

Request

Request Headers

Request Parameters

Request Body

Response

Response Body

Examples

Request

Request Headers

Request Body

Response

Response Body

Examples

Request

Request Headers

Request Body

Sample JSON

Response

Response Body

Examples

Request

Request Headers

Request Parameters

Request Body

Response

Response Body

Examples

Request

Request Header

Request Parameters

Response

Response Body

Examples

Request

Request Headers

Request Parameters

Response

Response Body

Example

Request

Response

Request

Request Headers

Request Parameters

Response

Response Body

Examples

Response: