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

The Audience API specification provides information on how data providers can integrate with PubMatic Audience.

Methods

Method Path	HTTP Method Type	Description	Link to Definition
/audiences/{audienceId}	GET	Retrieve the details of a particular audience from the PubMatic system for a specific data provider.	Retrieving Details of a Specific Audience
/audiences	GET	Retrieve the list of details of all the audiences present in the PubMatic system for a specific data provider.	Retrieving Details of all Audiences
/audiences	POST	Create an audience in the PubMatic system for a specific data provider.	Creating an Audience

Retrieving Details of a Specific Audience

Overview

This API allows you to retrieve the details of a particular audience from the PubMatic system for a specific data provider.

Request

URI	{uri-prefix}/audience/audiences/{audienceId}
HTTP Method	GET

Request Headers

Header Name

Value

Required

Description

pubToken

String

${access_token}

Yes

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

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

Content-Type

String

application/json

Yes

Specifies the content type of the request. Must be application/json.

Request Parameters

Parameter	Required	Validations	Description
accountId	Conditional	Yes	Id of an account in the PubMatic system. This is mandatory if the account is in the PubMatic system.
accountType	Yes	Yes	Type of account in the PubMatic system to which the audience belongs. Its value should be DATA_PROVIDER_CLIENT if this API is being called by a data provider.
clientId	Conditional	Yes	ID of the account in the data provider's system to which the audience belongs. Note: This parameter is mandatory if the "accountType" parameter mentioned above is set to DATA_PROVIDER_CLIENT.
dataProviderId	Conditional	Yes	ID of the data provider in the PubMatic system. Note: This parameter is mandatory if the "accountType" parameter mentioned above is set to DATA_PROVIDER_CLIENT.

Response

Response Body

Parameter	Description
id	Unique identifier of an audience in the PubMatic system.
name	Name of an audience.
description	Description of the audience.
definition	Rule definition of the audience. For example, "Male AND AGE < 24" Note: This is applicable only for the audiences managed by data provider's system and not by PubMatic.
enabled	Indicates whether or not the audience is enabled to be used in deals and rules. Possible options are: 0 - Disabled 1 - Enabled
private	Indicates whether the audience can be shared or not with other accounts in the PubMatic system. Possible options are: 0 - Shared audience 1 - Private audience
parentAudienceId	ID of the hierarchical parent of the audience. If its value is 0, then there is no hierarchy maintained.
accountId	ID of the account in the PubMatic system to which the audience belongs.
accountType	Type of account in the PubMatic system for which the audience belongs (e.g., PUBLISHER). Its value should be DATA_PROVIDER_CLIENT if this API is being called by a data provider.
accountName	Name of the account in the PubMatic system to which the audience belongs.
enabledForAIMTag	Indicates whether the audience is enabled or not to be sent in the AIM tag response. Possible options are: 0 - Disabled 1 - Enabled
dataProviderId	ID of the data provider in the PubMatic system for the audience.
dataProviderName	Name of the data provider for the audience.
providerAudienceId	ID of the audience in the data provider's system.
clientId	ID of the account in data provider's system to which the audience belongs (identified by the account ID and account type in the PubMatic system).
transferCode	Transfer code used for the audience when it is transferred from the data provider's system to the PubMatic system.
audienceGroupId	ID of the audience group to which the audience belongs.
dataTypeId	Data category to which the audience belongs. Possible options are: -1 - Unknown 1 - Traffic 2 - Demographic 3 - Interest 4 - Behavioural 5 - Content Safety 6 - Contextual
queryPostfix	IDs of the audience's rule definition using the postfix notation. This parameter is used for internal processing.
queryInfix	IDs of the audience's rule definition using the infix notation. This parameter is used for internal processing.
uniqueAudiences	IDs of the individual audiences used to create the audience.
creationTime	Timestamp (in the YYYY-MM-DD HH:MM:SS 24-hour format) at which the audience was created.
modificationTime	Timestamp (in the YYYY-MM-DD HH:MM:SS 24-hour format) at which the audience was last modified.
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,
"parentAudienceId": 0,
"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"
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Error Codes

Error Code	Error Description
AUD01_0037	Please provide a valid account type ID.
AUD01_0026	Please provide a valid client ID. It's length shouldn't be more than 1024 characters.
AUD01_0005	Please provide a valid data provider ID.
AUD01_0004	Please provide a valid account ID or data provider client ID.
AUD01_0036	Please provide a valid account ID.
CC03_0001	No records found.

Sample Error Response

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

Examples

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

Request

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

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,
"parentAudienceId": 0,
"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"
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Example 2: External call where client id is mandatory

Request

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

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,
"parentAudienceId": 0,
"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"
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Example 3: Call with invalid request parameters

Request

GET {uri-prefix}/audience/audiences/162534?accountType=PUBLISHER

Response

[
  {
    "errorCode": "AUD01_0026",
    "errorMessage": "Please provide a valid client ID."
  }
]‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Retrieving a List of All Audiences

Overview

This API allows you to retrieve the list of details of all the audiences present in the PubMatic system for a specific data provider.

Request

URI	{uri-prefix}/audience/audiences
HTTP Method	GET

Request Headers

Header Name

Value

Required

Description

pubToken

String

${access_token}

Yes

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

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

Content-Type

String

application/json

Yes

Specifies the content type of the request. Must be application/json.

Request Parameters

Parameter	Required	Validations	Description
accountId	Conditional	Yes	Id of an account in the PubMatic system. This is a mandatory parameter for PubMatic accounts.
accountType	Yes	Yes	Type of account in the PubMatic system for which the audience belongs (e.g., PUBLISHER). Its value should be DATA_PROVIDER_CLIENT if this API is being called by a data provider.
audienceType	No	Yes	Type of audiences in the PubMatic system. This parameter accepts multiple audience types (MY_AUDIENCE, SHARED_AUDIENCE, ALL_AUDIENCE). e.g. audienceType=MY_AUDIENCE&audienceType=SHARED_AUDIENCE Default values is MY_AUDIENCE
clientId	Conditional	Yes	ID of the account in the data provider's system to which the audience belongs. Note: This parameter is mandatory if the "accountType" parameter is set to DATA_PROVIDER_CLIENT.
dataProviderId	Conditional	Yes	ID of the data provider in the PubMatic system for the audience. Note: This parameter is mandatory if the "accountType" parameter is set to DATA_PROVIDER_CLIENT.
id	No	No	ID of the audience.
name	No	No	Name of the audience.
searchKey	No	No	Search string which will match against the name or ID of an audience.
providerAudienceId	No	No	ID of the audience in the data provider's system.
enabled	No	No	Filters the audiences on the basis of whether they are enabled to be used in deals and rules. Possible options are: 1 - Enabled 0 - Disabled
private	No	No	Filters audiences on the basis of whether they are shared with other accounts in the PubMatic system. Possible options are: 1 - Private audience (Cannot be shared with other accounts using PubMatic's audience system.) 0 - Shared audience
baseAudience	No	No	Filters audiences on the basis of whether they contain simple or complex rules. Possible options are: 1 - Base audience (audiences which do not contain any AND/OR rules, such as "Males, Females") 0 - Complex audience (audiences which contain AND/OR rules, such as "Males AND New York residents AND age group 20-30")
dataProviderOrganizationName	No	No	Name of the Data Provider Organization
dataProviderOrganizationId	No	No	Id of the Data Provider Organization

Response

Response Body

Parameter	Description
id	Unique identifier of the audience in the PubMatic system.
name	Name of the the audience.
accountId	ID of the account in the PubMatic system.
accountType	Type of the account on PubMatic system. Response should never have DATA_PROVIDER_CLIENT as account type. This type is only to be used as a request parameter value as the data provider calling API may not have account ID of the client on PubMatic's system, therefore, it would pass the clientId instead of the accountId in the request.
accountName	Name of the account in the PubMatic system.
providerAudienceId	ID of the audience in data provider's system.
enabledForAIMTag	If 1, this audience will be sent in response to AIM tag call.
dataProviderId	Data Provider Id for this audience.
dataProviderName	Name of the data provider.
clientId	ID of the account in data provider's system. (Identified by account Id and account type in the PubMatic system.)
transferCode	Transfer code for the audience
definition	Rule definition of the audience. This is applicable to audiences managed by a data platform, not by PubMatic.
description	Description of the audience
audienceGroupId	ID of the audience group to which the audience belongs.
dataTypeId	Data category to which the audience belongs. Possible options are: -1 - Unknown 1 - Traffic 2 - Demographic 3 - Interest 4 - Behavioural 5 - Content Safety 6 - Contextual
queryPostfix	IDs of the audience's rule definition using the postfix notation. This parameter is used for internal processing.
queryInfix	IDs of the audience's rule definition using the infix notation. This parameter is used for internal processing.
uniqueAudiences	Unique audiences used to create this audience.
enabled	This flag defines whether this audience is enabled or not. If 0, audience will not be available for creating deals or rules.
creationTime	Creation time for this audience. (YYYY-MM-DD HH:MM:SS 24-hour format.)
modificationTime	Last modification time for this audience (YYYY-MM-DD HH:MM:SS 24-hour format).
favourite
price	The price associated with the audience.
private	If 1, this audience can't be shared with any other account.
parentAudienceId	Hierarchical parent of the audience. 0 if no hierarchy is maintained.

Sample JSON

{
     "metaData": {
        "endRecordNumber": "2",
        "startRecordNumber": "1",
        "pageSize": "2",
        "pageNumber": "1",
        "numberOfPages": "12",
        "totalRecords": "23"
     },

     "items": [{
        "id": 23966,
        "name": "sadfsafsd",
        "longName": "sadfsafsd",
        "accountId": 31400,
        "accountName": "http://test.com",
        "accountType": "PUBLISHER",
        "providerAudienceId": "asd12345678",
        "transferCode": "asd12345678",
        "definition": "test1",
        "description": "sdf",
        "queryPostfix": "180:asd12345678",
        "queryInfix": "(,180:asd12345678,)",
        "uniqueAudiences": "180:asd12345678",
        "enabled": 1,
        "audienceGroupId": 1,
        "creationTime": "Sep 14, 2017",
        "modificationTime": "Sep 14, 2017",
        "favourite": "FALSE",
        "price": 12344,
        "private": 1,
        "dataProviderId": "180",
        "dataProviderName": "Adobe For 31400"
     },
     {

        "id": 23964,
        "name": "Test_for_empty_Price",
        "longName": "Test_for_empty_Price",
        "accountId": 31400,
        "accountName": "http://test.com",
        "accountType": "PUBLISHER",
        "providerAudienceId": "Asdf123_4",
        "transferCode": "Asdf123_4",
        "definition": "Test_for_empty_Price",
        "description": "test",
        "queryPostfix": "99:Asdf123_4",
        "queryInfix": "(,99:Asdf123_4,)",
        "uniqueAudiences": "99:Asdf123_4",
        "enabled": 1,
        "audienceGroupId": 1,
        "creationTime": "Aug 18, 2017",
        "modificationTime": "Aug 18, 2017",
        "favourite": "FALSE",
        "price": 23,
        "private": 1,
        "dataProviderId": "99",
        "dataProviderName": "Adobe For AccountId 31400"
     }]
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Error Codes

Error Code	Error Description
AUD01_0037	Please provide a valid account type ID.
AUD01_0026	Please provide a valid client ID. It's length shouldn't be more than 1024 characters.
AUD01_0005	Please provide a valid data provider ID.
AUD01_0004	Please provide a valid account ID or data provider client ID.
AUD01_0036	Please provide a valid account ID.
CC03_0001	No records found.

Sample Error Response

[
  {
    "errorCode": "AUD01_0026",
    "errorMessage": "Please provide a valid client ID. It's length shouldn't be more than 1024 characters."
  }
]‍‍‍‍‍‍

Examples

Example 1: Internal call where account Id is mandatory

Request

GET {uri-prefix}/audience/audiences?accountId=27332341&accountType=PUBLISHER

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,
"parentAudienceId": 0,
"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"
},
{
"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,
"parentAudienceId": 0,
"accountId": 27332341,
"accountType": "PUBLISHER",
"accountName": "Some Publisher",
"enabledForAIMTag": 0,
"dataProviderId": 383,
"dataProviderName": "Some data provider",
"providerAudienceId": "71",
"clientId": "345343",
"transferCode": "142323213",
"audienceGroupId": "1",
"dataTypeId": "-1",
"queryPostfix": "383:71",
"queryInfix": "(,383:71,)",
"uniqueAudiences": "383:71"
}
]‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Example 2: External call where client Id is mandatory

Request

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

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,
"parentAudienceId": 0,
"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"
},
{
"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,
"parentAudienceId": 0,
"accountId": 27332341,
"accountType": "PUBLISHER",
"accountName": "Some Publisher",
"enabledForAIMTag": 0,
"dataProviderId": 383,
"dataProviderName": "Some data provider",
"providerAudienceId": "71",
"clientId": "345343",
"transferCode": "142323213",
"audienceGroupId": "1",
"dataTypeId": "-1",
"queryPostfix": "383:71",
"queryInfix": "(,383:71,)",
"uniqueAudiences": "383:71"
}
]‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Example 3: Call with invalid request parameters

Request

GET {uri-prefix}/audience/audiences?accountType=PUBLISHER

Response

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

Create a Segment

Overview

This API allows you to create an segment in the PubMatic system for a specific data provider using either of the following methods:

Using PubMatic account Id values. DMPs can register an audience by providing the account_type parameter as one of PUBLISHER, DEMAND_PARTNER or BUYER and the corresponding Id that is present in the PubMatic system in the account_id parameter.
OR
Using the Data Provider's system Id for the publisher, buyer or DSP account. The account_type parameter is DATA_PROVIDER_CLIENT and the client_id parameter is the data provider Id, which identifies the publisher, buyer or DSP.

Note: If the client plans to use client_id while creating an audience, this should be provided in advance to the Audience Operations Team prior to creating a DPID in the PubMatic system.

Request

URI	{uri-prefix}/audience/audiences
HTTP Method	POST

Request Headers

Header Name

Value

Required

Description

pubToken

String

${access_token}

Yes

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

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

Content-Type

String

application/json

Yes

Specifies the content type of the request. Must be application/json.

Request Body

Parameter	Required	Validations	Description
name	Yes	Length <= 256	Name of the audience to be created.
description	No	Length <= 1024	Description for this audience.
definition	Conditional	Length <= 1024	Rule definition of this audience, that is, its constituents. For example, "Male AND AGE < 24". Note: This is applicable only for the audiences managed by data provider's system and not by PubMatic. In the PubMatic system, this just represents a textual representation of audience's rule definition.
enabled	No	Value should be either 0 or 1. In case of an empty value or an invalid value, its default value is 1.	Indicates whether this audience is enabled to be used in deals and rules or not. Possible options are: 0 - Disabled 1 - Enabled
private	No	Value should be either 0 or 1. In case of an empty value or an invalid value, its default value is 1.	Indicates whether the audience can be shared or not with other accounts in the PubMatic system. Possible options are: 0 - Shared audience 1 - Private audience
accountId	Conditional	Mandatory if accountType is PUBLISHER, DEMAND_PARTNER, or BUYER.	Publisher ID, Buyer ID, or DSP Id should be passed against this field if account type is PUBLISHER, BUYER, or DEMAND_PARTNER, respectively.
accountType	Yes	Mandatory and should be either PUBLISHER, DEMAND_PARTNER, BUYER, or DATA_PROVIDER_CLIENT.	Type of the data provider's account in the PubMatic system to which the audience belongs. The response will never have DATA_PROVIDER_CLIENT as the account type. This type is reserved to be used as a request parameter value, as the data provider who is making the API call may not have an account ID for a client in the PubMatic system. Therefore, it will pass the clientId instead of accountId in the 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 is being created is not a complex audience. i.e., audience with AND/OR between multiple audiences	ID of the data provider in the PubMatic system for this audience.
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		Transfer code used for the audience when it is transferred from the data provider's system to the PubMatic system.Transfer code is the same as "providerAudienceId" for most of the data providers. If it is different, then it has to be passed explicitly; otherwise its default value is set to the value of "providerAudienceId".
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 it.

Sample JSON

There are two JSON request payloads this API works with. Depending on which payload is used, a determination is made whether to register a simple audience without complex rule or a complex audience with multiple simple audiences used with AND/OR between them.

Example 1: Sample JSON that registers 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"
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Example 2: Sample JSON that registers a complex audience. In this example, a validation of queryInfix to check if all base audiences used to create this audience are already registered in the PubMatic system.

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

‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Response

Response Body

Parameter	Description
id	Unique identifier of the audience in the PubMatic system.
name	Name of the audience.
description	Description of the audience.
definition	Rule definition of the audience, that is, its constituents. For example, "Male AND AGE < 24". Note: This is applicable only for the audiences managed by data provider's system and not by PubMatic.
enabled	Indicates whether or not the audience is enabled to be used in deals and rules. Possible options are: 0 - Disabled 1 - Enabled
private	Indicates whether the audience can be shared or not with other accounts in the PubMatic system. Possible options are: 0 - Shared audience 1 - Private audience
parentAudienceId	ID of the hierarchical parent of the audience. If its value is 0, then there is no hierarchy maintained.
accountId	ID of the account in the PubMatic system to which the audience belongs.
accountType	Type of the account in the PubMatic system to which the audience belongs. For example, "PUBLISHER".
accountName	Name of the account in the PubMatic system to which the audience belongs.
enabledForAIMTag	Indicates whether the audience is enabled or not to be sent in the AIM tag response. Possible options are: 0 - Disabled 1 - Enabled
dataProviderId	ID of the data provider in the PubMatic system for the audience.
dataProviderName	Name of the data provider for the audience.
providerAudienceId	ID of the audience in the data provider's system.
clientId	ID of the account in data provider's system to which the audience belongs (identified by the account ID and account type in the PubMatic system).
transferCode	Transfer code used for the audience when it is transferred from the data provider's system to the PubMatic system.
audienceGroupId	ID of the audience group to which the audience belongs.
dataTypeId	Data category to which the audience belongs. Possible options are: -1 - Unknown 1 - Traffic 2 - Demographic 3 - Interest 4 - Behavioural 5 - Content Safety 6 - Contextual
queryPostfix	IDs of the audience's rule definition using the postfix notation. This parameter is used for internal processing.
queryInfix	IDs of the audience's rule definition using the infix notation. This parameter is used for internal processing.
uniqueAudiences	IDs of the individual audiences used to create the audience.
creationTime	Timestamp (in the YYYY-MM-DD HH:MM:SS 24-hour format) at which the audience was created.
modificationTime	Timestamp (in the YYYY-MM-DD HH:MM:SS 24-hour format) at which the audience was last modified.
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,
"parentAudienceId": 0,
"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"
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Error Codes

Error codes specific to this API method.

Error Codes	Error Description
AUD01_0003	Please provide an audience.
AUD01_0005	Please provide a valid data provider ID.
AUD01_0037	Please provide a valid account type 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_0026	Please provide a valid client ID. 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_0031	Data Provider is not associated with data provider client.
AUD01_0013	Data Provider is not associated with Publisher.
AUD01_0014	Audience already exists.
AUD01_0153	Price cannot be negative

Error codes specific to API calls to create a non-complex audience

Error Codes	Error Description
AUD01_0003	Please provide an audience.
AUD01_0005	Please provide a valid data provider ID.
AUD01_0037	Please provide a valid account type 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_0026	Please provide a valid client ID. 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_0031	Data Provider is not associated with data provider client.
AUD01_0013	Data Provider is not associated with Publisher.
AUD01_0014	Audience already exists.

Error codes specific to API calls to create a non-complex audience

Error Codes	Error Description
AUD01_0003	Please provide an audience.
AUD01_0037	Please provide a valid account type 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_0034	Query validation failed.
AUD01_0035	Audience with same name already present. Please use different name.

Examples

Example 1: Creating a simple audience with no complex rule.

The rule is managed by DMP and PubMatic system stores its meta data.

Request:

POST {uri-prefix} /audience/audiences

{
    "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,
"parentAudienceId": 0,
"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"
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Example 2: Creating a complex audience.

Request:

POST {uri-prefix} /audience/audiences

{
    "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 a complex audience with invalid base audience in the rule.

Request:

POST {uri-prefix} /audience/audiences

{
    "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."
       }
]‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

⇧ Top

Page tree

Audience API

Methods

Retrieving Details of a Specific Audience

Overview

Request

Request Headers

Request Parameters

Response

Response Body

Sample JSON:

Error Codes

Sample Error Response

Examples

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

Request

Response

Example 2: External call where client id is mandatory

Request

Response

Example 3: Call with invalid request parameters

Request

Response

Retrieving a List of All Audiences

Overview

Request

Request Headers

Request Parameters

Response

Response Body

Sample JSON

Error Codes

Sample Error Response

Examples

Example 1: Internal call where account Id is mandatory

Request

Response

Example 2: External call where client Id is mandatory

Request

Response

Example 3: Call with invalid request parameters

Request

Response

Create a Segment

Overview

Request

Request Headers

Request Body

Sample JSON

Example 1: Sample JSON that registers a simple audience.

Example 2: Sample JSON that registers a complex audience. In this example, a validation of queryInfix to check if all base audiences used to create this audience are already registered in the PubMatic system.

Response

Response Body

Sample JSON

Error Codes

Error codes specific to this API method.

Error codes specific to API calls to create a non-complex audience

Examples

Example 1: Creating a simple audience with no complex rule.

Request:

Response:

Example 2: Creating a complex audience.

Request:

Response:

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

Request:

Response: