- Created by Janessa Johnson, last modified by Catherine Racette on Nov 02, 2018
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:
|
| private | Indicates whether the audience can be shared or not with other accounts in the PubMatic system. Possible options are:
|
| 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:
|
| 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:
|
| 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 |
| 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:
|
| private | No | No | Filters audiences on the basis of whether they are shared with other accounts in the PubMatic system. Possible options are:
|
| baseAudience | No | No | Filters audiences on the basis of whether they contain simple or complex rules. Possible options are:
|
| 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:
|
| 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 an Audience
Overview
This API allows you to create an audience 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:
|
| 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:
|
| 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:
|
| private | Indicates whether the audience can be shared or not with other accounts in the PubMatic system. Possible options are:
|
| 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:
|
| 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:
|
| 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."
}
]