Go to start of metadata
Skip to end of metadata
Go to start of metadata
- Created by PubMatic Technical Documentation, last modified by Mindy Carpenter on Feb 28, 2021
Audience API
The Audience API lets buyers and publishers integrate data providers with PubMatic Audiences. For production, replace ${uri-prefix} with: http://api.pubmatic.com ${uri-prefix}/audience/audiences Retrieve the details for a specific audience on the PubMatic platform. ${uri-prefix} /audiences/{audienceId} ${uri-prefix}/audiences/bulk ${uri-prefix}/audiences/downloadCreateAudienceTemplate 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. For production, replace ${uri-prefix} with: http://api.pubmatic.com 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 For more information about our access tokens, see Getting Started with PubMatic APIs. audienceType No request body is expected. 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 For more information on using our access tokens, see Getting Started with PubMatic APIs. Example 1: Internal call where account ID is a mandatory parameter Request: Example 2: External call where client ID is mandatory Request: Example 3: Call with invalid request parameters. Request: Before you begin: For production, replace ${uri-prefix} with: http://api.pubmatic.com 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 For more information about access tokens, see Getting Started with PubMatic APIs. Body Parameter Required Validations Description name description enabled accountId accountType Mandatory and among PUBLISHER, and DATA_PROVIDER_CLIENT enabledForAIMTag dataProviderId clientId transferCode price 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 For more information about access tokens, see Getting Started with PubMatic APIs. Body Parameter Description id name description definition enabled private accountId accountType accountName enabledForAIMTag dataProviderId dataProviderName providerAudienceId clientId transferCode audienceGroupId queryPostfix queryInfix uniqueAudiences creationTime modificationTime price Example 1: Valid request to update name of an audience. Request: Example 2: A request with incorrect data provider ID There are two ways to register a new audience segment in the PubMatic system: OR 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 For more information about access tokens, see Getting Started with PubMatic APIs. Body Parameter Required Validations Description name Yes Mandatory and length <= 256 description No length <= 1024 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: 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 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. 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 2: Registration of a complex audience. A validation of queryInfix is performed to check if all base audiences are already registered on PubMatic platform. Response Body Parameter Description 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 Example 1: Creating a simple audience with no complex rule. The rule is managed by DMP, and the PubMatic platform stores its metadata. Request: Response: E xample 2: Creating a complex audience. Request: Response: Example 3: Creating complex audience with an invalid base audience in rule. Request: Response: Modify fields for multiple audiences in a single call on the PubMatic platform. Before you begin: 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 For more information about access tokens, see Getting Started with PubMatic APIs. No request parameters are expected. Body Parameter Required Validations Description Response Body Parameter Description Example 1: Valid request to update name of an audience. Response: Example 2: Request with incorrect data provider ID. Retrieve the details for a specific audience on the PubMatic platform. For production, replace ${uri-prefix} with: http://api.pubmatic.com 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 For more information about access tokens, see Getting Started with PubMatic APIs. 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. Example 1: Internal call where account Id is mandatory parameter. Request: ${uri-prefix}/audiences/475332?accountId=27332341&accountType=PUBLISHER Example 2: External call where client ID is mandatory. Request: ${uri-prefix}/audiences/475332?clientId=345343&accountType=DATA_PROVIDER_CLIENT&dataProviderId=383 Response: Example 3: Call with invalid request parameters. Request: Response: Use this API to download a (CSV file) template that enables you tocreate anaudience in bulk. Some highlights of this template: 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 For more information about access tokens, see Getting Started with PubMatic APIs. accountId Data Provider ID PubMatic Segment ID Source Segment ID Segment Name PubMatic Account ID Data Price Enabled? Source Client ID Comments Valid request to download create audience template. ${uri-prefix}/audience/audiences/downloadCreateAudienceTemplate?accountId=31400 Data Provider ID PubMatic Segment ID Source Segment ID Segment Name PubMatic Account ID Data Price Enabled? Source Client ID Comments Use this API to download a CSV template that allows you to update audiences in bulk. Some highlight of this template: 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 For more information on using our access tokens, see Getting Started with PubMatic APIs. Data Provider ID PubMatic Segment ID Source Segment ID Segment Name PubMatic Account ID Data Price Enabled? Source Client ID Comments Valid request to download update audience template. Header name Data Provider ID PubMatic Segment ID Source Segment ID Segment Name PubMatic Account ID Data Price Enabled? Source Client ID Comments Before using PubMatic APIs, first generate the API Access Token. For more information, see Getting Started with PubMatic APIs.Supported Operations
Single Audience operations
Link to documentation Method Path Type Description Retrieve a list of audiences GET Retrieve a list of audiences registered under the same account on the PubMatic platform. Retrieve audience details ${uri-prefix}/audiences/{audienceId} GET Register a new audience ${uri-prefix}/v1/audiences POST Register new audience segments on the PubMatic platform. Update an audience PATCH Modify these fields for an audience on PubMatic platform: name, description, price and enabled flag. Update multiple audiences 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 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
Retrieve a list of audiences
Request
URI ${uri-prefix}/audiences Method GET Request Headers
Header Name Type Value Required Description ${access_token} in the request.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" 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_AUDIENCEdataProviderOrganizationName No No Name of the Data Provider Organization dataProviderOrganizationId No No Id of the Data Provider Organization Request Body
Sample request URL
http://localhost:8018/audience/audiences?accountId=31400&accountType=PUBLISHER
Response
Header Name Type Value Required Description ${access_token} in the request.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
URI ${uri-prefix}/audiences?accountId=27332341&accountType=PUBLISHER Method GET
Response
Expand source
{
"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"
}]
]
URI ${uri-prefix}/audiences?clientId=345343&accountType=DATA_PROVIDER_CLIENT&dataProviderId=383 Method GET
Response
Expand source
{
"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"
}]
]
URI ${uri-prefix}/audiences?accountType=PUBLISHER Method GET
Update an audience
Request
URI ${uri-prefix}/audiences/{audienceId} Method PATCH Request Headers
Header Name Type Value Required Description ${access_token} in the request.Content-Type String application/JSON Yes Media type for the request. Request Body
No Mandatory and length <= 256 No length <= 1024 No Value should be 0 or 1. otherwise defaulted to 1. In case of no value or invalid value, defaulted to 1. Conditional Mandatory if accountType is PUBLISHER. Publisher ID should be passed against this field in account type is PUBLISHER. Yes 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. Yes Id of data provider on PubMatic platform for which the audience is being created. Conditional Mandatory if accountType is DATA_PROVIDER_CLIENT. 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. 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
Expand source
{
"accountId":27332341,
"accountType":"PUBLISHER",
"name":"Travel Enthusiasts",
"description":"test",
"dataProviderId":"383",
"transferCode":"14232323",
"price":"1.0"
}
Response
Header Name Type Value Required Description ${access_token} in the request.Content-Type String application/JSON Yes Media type for the request. Response Body
Unique Identifier for an audience registered on PubMatic platform. Name of the audience. Description of the audience. Rule definition of an audience. This is applicable to audiences managed by data platform and not by PubMatic. This flag defines whether this audience is enabled or not. If 0, audience won't be available for creating deals or rules. If 1, this audience can't be shared with any other account. Id of account on PubMatic platform. Type of an account on PubMatic platform. Name of account on PubMatic platform. If 1, this audience would be sent in response to AIM tag call. Data Provider Id for this audience. Name of the data provider. Id of this audience on data provider's platform. Id of this account on data provider's platform. (identified by account Id and account type on PubMatic platform). Transfer code for an audience. audience group id for this audience. Rule for this audience. Unique audiences used to create this audience. Creation time for this audience. Last modification time for this audience. The price to which the audience is updated.
Sample Response JSON
Expand source
{
"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
URI ${uri-prefix}/audiences/475332 Method PATCH
Sample request
Expand source
{
"accountId":27332341,
"accountType":"PUBLISHER",
"name":"Travel Enthusiasts updated",
"description":"test",
"dataProviderId":"383",
"transferCode":"14232323",
"price":"1.0"
}
Sample response
Expand source
{
"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"
}
Request:URI ${uri-prefix}/audiences/475332 Method PATCH
Sample request
Expand source
{
"accountId":27332341,
"accountType":"PUBLISHER",
"name":"Travel Enthusiasts updated",
"description":"test",
"dataProviderId":"3834",
"transferCode":"14232323",
"price":"1.0"
}
Sample response
Expand source
[
{
"errorCode": "AUD01_0005",
"errorMessage": "Please provide a valid data provider ID."
}
]
Register a new audience
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.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/audiences Method POST Request Headers
Header Name Type Value Required Description ${access_token} in the request.Content-Type String application/json Yes Media type for the request. Request Body
The name of the new audience segment; for example, "Automobile Buyers". An optional description of the purpose, target, and any other relevant information about this audience segment. clientId instead of accountId in request.Sample JSON
Sample JSON request
Expand source
{
"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 JSON request
Expand source
{
"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
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 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
Expand source
{
"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
URI ${uri-prefix}/v1/audiences Method POST
Sample JSON request body
Expand source
{
"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 JSON response
Expand source
{
"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"
}
URI ${uri-prefix}/v1/audiences Method POST
Sample JSON request body
Expand source
{
"accountId":27332341,
"accountTypeId":"PUBLISHER",
"name":"Travel Enthusiasts",
"description":"test",
"queryInfix":"(,383:216804,AND,383:223315,AND,383:183659,AND,383:183663,)"
}
Sample JSON response
Expand source
{
"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"
}
URI ${uri-prefix}/v1/audiences Method POST
Sample JSON request body
Expand source
{
"accountId":27332341,
"accountTypeId":"PUBLISHER",
"name":"Travel Enthusiasts",
"description":"test",
"queryInfix":"(,383:216804393,AND,383:223315,AND,383:183659,AND,383:183663,)"
}
Sample response
Expand source
[
{
"errorCode": "AUD01_0034",
"errorMessage": "Query validation failed."
}
]
Update multiple audiences
Request
URI ${uri-prefix}/audiences/bulk Method PATCH Request Headers
Header Name Type Value Required Description ${access_token} in the request.Content-Type String application/json Yes Media type for the request. Request Parameters
Request Body
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
Expand source
[
{
"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
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
Expand source
[
{
"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
URI ${uri-prefix}/audiences/bulk Method PATCH
Sample JSON request
Expand source
[
{
"id": 23900,
"name":"Travel Enthusiasts updated",
"accountId": 114634,
"accountType": "PUBLISHER",
"dataProviderId":"383",
"enabled": 0
}
]
Sample response
Expand source
[
{
"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"
}
]
URI ${uri-prefix}/audiences/475332 Method PATCH
Sample JSON request
Expand source
[
{
"id": 475332,
"accountId":27332341,
"accountType":"PUBLISHER",
"name":"Travel Enthusiasts updated",
"description":"test",
"dataProviderId":"3834",
"transferCode":"14232323",
"price":"1.0"
}
}
Sample response
Expand source
[
{
"errorCode": "AUD01_0005",
"errorMessage": "Please provide a valid data provider ID."
}
]
Retrieve audience details
Request
URI ${uri-prefix}/audiences/{audienceId} Method GET Request Header
Header Name Type Value Required Description ${access_token} in the request.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
Sample response
Expand source
{
"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
URL Method GET
Sample response
Expand source
{
"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"
}
URL
Method GET
Sample response
Expand source
{
"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"
}
URL ${uri-prefix}/audiences/162534?accountType=PUBLISHER Method GET
Sample response
Expand source
[
{
"errorCode": "AUD01_0036",
"errorMessage": "Please provide a valid account ID."
}
]
Create audience template
Request
URI ${uri-prefix}/audiences/downloadCreateAudienceTemplate Method GET Request Headers
Header Name Type Value Required Description ${access_token} in the request.Request Parameters
Parameter Name Required Validations Description 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 Mandatory Leave blank for Create Mandatory Mandatory Mandatory CPM in USD Y/N Mandatory if account ID is blank Displays failure reason(s) Example
Request
URL
Method GET Response
Header name Validation Mandatory Leave blank for Create Mandatory Mandatory Mandatory CPM in USD Y/N Mandatory if account ID is blank Displays failure reason(s)
Update audience template
Request
URI ${uri-prefix}/audiences/downloadUpdateAudienceTemplate Method GET Request Headers
Header Name Type Value Required Description ${access_token} in the request.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 Mandatory Leave blank for Create Mandatory Mandatory Mandatory CPM in USD Y/N Mandatory if account ID is blank Displays failure reason(s) Examples
Sample Request URL
Expand source
${uri-prefix}/audience/audiences/downloadUpdateAudienceTemplate?accountType=PUBLISHER&accountId=31400
Response:
Validation Mandatory Leave blank for Create Mandatory Mandatory Mandatory CPM in USD Y/N Mandatory if account ID is blank 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
Expand source
[
{
"errorCode": "AUD01_0036",
"errorMessage": "Please provide a valid account ID."
}
]
Overview
Content Tools
Activity
PRIVACY
OPT-OUT
TERMS OF SERVICE
PUBMATIC LEGAL POLICIES
Copyright © 2021 PubMatic, Inc. All Rights Reserved
This website uses cookies for analytics and personalization. Click here to learn more or change your cookie settings. By continuing to browse, you agree to our use of cookies.