Audience API

Document created by pubmatic-archivist on Mar 27, 2017Last modified by catherine.racette on Aug 22, 2017
Version 6Show Document
  • View in full screen mode

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

Methods

                           

Method PathHTTP Method TypeDescriptionLink to Definition

/audiences/{audienceId}

GETRetrieve the details of a particular audience from the PubMatic system for a specific data provider.Retrieving Details of a Specific Audience

/audiences

GETRetrieve the list of details of all the audiences present in the PubMatic system for a specific data provider.Retrieving Details of all Audiences

/audiences

POSTCreate 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}/audiences/{audienceId}
HTTP MethodGET

Request Headers

                 

Header Name

Type

Value

Required

Description

Authorization

String

Bearer ${access_token}

Yes

Need to send the access token generating for authentication at the place of ${access_token}.

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

Request Parameters

                           

ParameterRequiredValidationsDescription
accountTypeYesYes

Type of account in the PubMatic platform to which the given audience belongs.

Its value should be DATA_PROVIDER_CLIENT if this API is being called by a data provider.

clientIdYesYes

ID of the account in the data provider's system to which the given audience belongs.

Note: This parameter is mandatory if the "accountType" parameter mentioned above is set to DATA_PROVIDER_CLIENT.

dataProviderIdYesYes

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

                                                                                                   

ParameterDescription
idUnique identifier of the audience in the PubMatic system.
nameName of the given audience.
descriptionDescription of the given audience.
definition

Rule definition of the given 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 the given audience is enabled to be used in deals and rules or not.

Possible options are:

  • 0 - Disabled
  • 1 - Enabled
private

Indicates whether the given audience can be shared or not with other accounts in the PubMatic system.

Possible options are:

  • 0 - Shared audience
  • 1 - Private audience
parentAudienceIdID of the hierarchical parent of the given audience. If its value is 0, then there is no hierarchy maintained.
accountIdID of the account in the PubMatic system to which the given audience belongs.
accountTypeType of the account in the PubMatic system to which the given audience belongs. For example, "PUBLISHER".
accountNameName of the account in the PubMatic system to which the given audience belongs.
enabledForAIMTag

Indicates whether the given audience is enabled or not to be sent in the AIM tag response.

Possible options are:

  • 0 - Disabled
  • 1 - Enabled
dataProviderIdID of the data provider in the PubMatic system for the given audience.
dataProviderNameName of the data provider for the given audience.
providerAudienceIdID of the given audience in the data provider's system.
clientIdID of the account in data provider's system to which the given audience belongs (identified by the account ID and account type in the PubMatic system).
transferCodeTransfer code used for the given audience when it is transferred from the data provider's system to the PubMatic system.
audienceGroupIdID of the audience group to which the given audience belongs.
dataTypeId

Data category to which the given audience belongs. Possible options are:

  • -1 - Unknown
  • 1 - Traffic
  • 2 - Demographic
  • 3 - Interest
  • 4 - Behavioural
  • 5 - Content Safety
  • 6 - Contextual
queryPostfixIDs of the given audience's rule definition using the postfix notation. This parameter is used for internal processing.
queryInfixIDs of the given audience's rule definition using the infix notation. This parameter is used for internal processing.
uniqueAudiencesIDs of the individual audiences used to create the given audience.
creationTimeTimestamp (in the YYYY-MM-DD HH:MM:SS 24-hour format) at which the given audience was created.
modificationTimeTimestamp (in the YYYY-MM-DD HH:MM:SS 24-hour format) at which the given audience was last modified.

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



Error Codes

                               

Error CodeError Description
AUD01_0037Please provide a valid account type ID.
AUD01_0026Please provide a valid client ID. It's length shouldn't be more than 1024 characters.
AUD01_0005Please provide a valid data provider ID.
AUD01_0004Please provide a valid account ID or data provider client ID.
AUD01_0036Please provide a valid account ID.
CC03_0001No records found.

Sample Error Response


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

Examples

Example 1: Valid Request

Request:


GET {uri-prefix}/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 2: Call with invalid request parameters

Request:

GET {uri-prefix}/audiences/162534?accountType=DATA_PROVIDER_CLIENT&dataProviderId=383

Response:

 

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

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}/audiences
HTTP MethodGET

Request Headers

                 

Header Name

Type

Value

Required

Description

Authorization

String

Bearer ${access_token}

Yes

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

 

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

Request Parameters

                                                                     

ParameterRequiredValidationsDescription
accountTypeYesYes

Type of account in the PubMatic platform to which the given audience belongs.

Its value should be DATA_PROVIDER_CLIENT if this API is being called by a data provider.

clientIdYesYes

ID of the account in the data provider's system to which the given audience belongs.

Note: This parameter is mandatory if the "accountType" parameter mentioned above is set to DATA_PROVIDER_CLIENT.

dataProviderIdYesYes

ID of the data provider in the PubMatic system for the given audience.

Note: This parameter is mandatory if the "accountType" parameter mentioned above is set to DATA_PROVIDER_CLIENT.

idNoNoID of the audience whose details need to be retrieved.
nameNoNoName of the audience whose details need to be retrieved.
searchKeyNoNoSearch string which will match against the name or ID of audiences whose details need to be retrieved.
providerAudienceIdNoNoID of the audience in the data provider's system, whose details need to be retrieved.
enabledNoNo

Filter the audiences on the basis of whether they are enabled to be used in deals and rules or not.

Possible options are:

  • 1 - Enabled
  • 0 - Disabled
privateNoNo

Filter the audiences on the basis of whether they are shared with other accounts in the PubMatic system or not,

Possible options are:

  • 1 - Private audience (that is, not shared with other accounts)
  • 0 - Shared audience
baseAudienceNoNoFilter the 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 OR rules, such as Males)
  • 0 - Complex audience (audiences which contain AND and/or OR rules, such as Males AND New York residents)

Response

Response Body

                                                                                                   

ParameterDescription
idUnique identifier of the audience in the PubMatic system.
nameName of the given audience.
descriptionDescription of the given audience.
definition

Rule definition of the given 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 the given audience is enabled to be used in deals and rules or not.

Possible options are:

  • 0 - Disabled
  • 1 - Enabled
private

Indicates whether the given audience can be shared or not with other accounts in the PubMatic system.

Possible options are:

  • 0 - Shared audience
  • 1 - Private audience
parentAudienceIdID of the hierarchical parent of the given audience. If its value is 0, then there is no hierarchy maintained.
accountIdID of the account in the PubMatic system to which the given audience belongs.
accountTypeType of the account in the PubMatic system to which the given audience belongs. For example, "PUBLISHER".
accountNameName of the account in the PubMatic system to which the given audience belongs.
enabledForAIMTag

Indicates whether the given audience is enabled or not to be sent in the AIM tag response.

Possible options are:

  • 0 - Disabled
  • 1 - Enabled
dataProviderIdID of the data provider in the PubMatic system for the given audience.
dataProviderNameName of the data provider for the given audience.
providerAudienceIdID of the given audience in the data provider's system.
clientIdID of the account in data provider's system to which the given audience belongs (identified by the account ID and account type in the PubMatic system).
transferCodeTransfer code used for the given audience when it is transferred from the data provider's system to the PubMatic system.
audienceGroupIdID of the audience group to which the given audience belongs.
dataTypeId

Data category to which the given audience belongs. Possible options are:

  • -1 - Unknown
  • 1 - Traffic
  • 2 - Demographic
  • 3 - Interest
  • 4 - Behavioural
  • 5 - Content Safety
  • 6 - Contextual
queryPostfixIDs of the given audience's rule definition using the postfix notation. This parameter is used for internal processing.
queryInfixIDs of the given audience's rule definition using the infix notation. This parameter is used for internal processing.
uniqueAudiencesIDs of the individual audiences used to create the given audience.
creationTimeTimestamp (in the YYYY-MM-DD HH:MM:SS 24-hour format) at which the given audience was created.
modificationTimeTimestamp (in the YYYY-MM-DD HH:MM:SS 24-hour format) at which the given audience was last modified.

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

Error Codes

                               

Error CodeError Description
AUD01_0037Please provide a valid account type ID.
AUD01_0026Please provide a valid client ID. It's length shouldn't be more than 1024 characters.
AUD01_0005Please provide a valid data provider ID.
AUD01_0004Please provide a valid account ID or data provider client ID.
AUD01_0036Please provide a valid account ID.
CC03_0001No 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:

Request

 

GET {uri-prefix}/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 2:

Call with invalid request parameters

Request

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

Response

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

Create an Audience

Overview

This API allows you to create an audience in the PubMatic system for a specific data provider.

Request

 

URI{uri-prefix}/audiences
HTTP MethodPOST

Request Headers

                        

Header Name

Type

Value

Required

Description

Content-Type

application/json

 

Yes

-

Authorization

String

Bearer ${access_token}

Yes

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

 

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

Request Body

                                                                           

Parameter RequiredValidationsDescription
nameYesMandatory and length <= 256Name of the audience to be created.
descriptionNoLength <= 1024Description for this audience.
definitionNoLength <= 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.

enabledNo

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
privateNo

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 given audience can be shared or not with other accounts in the PubMatic system.

Possible options are:

  • 0 - Shared audience
  • 1 - Private audience
accountTypeYesMandatory and should be DATA_PROVIDER_CLIENT for requests from a data provider.Type of the data provider's account in the PubMatic system to which the given audience belongs.
enabledForAIMTagNo Indicates whether the given audience is enabled or not to be sent in the AIM tag response.
Possible options are:
  • 0 - Disabled
  • 1 - Enabled
dataProviderIdYes ID of the data provider in the PubMatic system for this audience.
providerAudienceIdYes ID of this audience in the data provider's system.
clientIdYes ID of the account in the data provider's system to which the given audience belongs (identified by the account ID and account type in the PubMatic system).
transferCodeNo Transfer code used for the given 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".

Sample JSON:

 

{
  "clientId":"345343",
  "accountType":"DATA_PROVIDER_CLIENT",
  "name":"Travel Enthusiasts",
  "description":"test",
  "dataProviderId":"383",
  "definition":"Male AND AGE < 24 AND EDU=PHOTO",
  "providerAudienceId":"7",
  "transferCode":"14232323"
}

 

 

Response

Response Body

                                                                                                   

ParameterDescription
idUnique identifier of the audience in the PubMatic system.
nameName of the given audience.
descriptionDescription of the given audience.
definition

Rule definition of the given 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 the given audience is enabled to be used in deals and rules or not.

Possible options are:

  • 0 - Disabled
  • 1 - Enabled
private

Indicates whether the given audience can be shared or not with other accounts in the PubMatic system.

Possible options are:

  • 0 - Shared audience
  • 1 - Private audience
parentAudienceIdID of the hierarchical parent of the given audience. If its value is 0, then there is no hierarchy maintained.
accountIdID of the account in the PubMatic system to which the given audience belongs.
accountTypeType of the account in the PubMatic system to which the given audience belongs. For example, "PUBLISHER".
accountNameName of the account in the PubMatic system to which the given audience belongs.
enabledForAIMTag

Indicates whether the given audience is enabled or not to be sent in the AIM tag response.

Possible options are:

  • 0 - Disabled
  • 1 - Enabled
dataProviderIdID of the data provider in the PubMatic system for the given audience.
dataProviderNameName of the data provider for the given audience.
providerAudienceIdID of the given audience in the data provider's system.
clientIdID of the account in data provider's system to which the given audience belongs (identified by the account ID and account type in the PubMatic system).
transferCodeTransfer code used for the given audience when it is transferred from the data provider's system to the PubMatic system.
audienceGroupIdID of the audience group to which the given audience belongs.
dataTypeId

Data category to which the given audience belongs. Possible options are:

  • -1 - Unknown
  • 1 - Traffic
  • 2 - Demographic
  • 3 - Interest
  • 4 - Behavioural
  • 5 - Content Safety
  • 6 - Contextual
queryPostfixIDs of the given audience's rule definition using the postfix notation. This parameter is used for internal processing.
queryInfixIDs of the given audience's rule definition using the infix notation. This parameter is used for internal processing.
uniqueAudiencesIDs of the individual audiences used to create the given audience.
creationTimeTimestamp (in the YYYY-MM-DD HH:MM:SS 24-hour format) at which the given audience was created.
modificationTimeTimestamp (in the YYYY-MM-DD HH:MM:SS 24-hour format) at which the given audience was last modified.

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

Error Codes

                                                       

Error CodesError Description
AUD01_0003Please provide an audience.
AUD01_0005Please provide a valid data provider ID.
AUD01_0037Please provide a valid account type ID.
AUD01_0008Please provide a valid audience name. It's length shouldn't be more than 256 characters.
AUD01_0009Please provide a valid audience description. It's length shouldn't be more than 1024 characters.
AUD01_0026Please provide a valid client ID. It's length shouldn't be more than 1024 characters.
AUD01_0010Please provide a valid provider audience ID. It's length shouldn't be more than 256 characters.
AUD01_0011Please provide a valid audience definition. It's length shouldn't be more than 1024 characters.
AUD01_0012Please provide a valid transfer code. It's length shouldn't be more than 256 characters.
AUD01_0031Data Provider is not associated with data provider client.
AUD01_0013Data Provider is not associated with Publisher.
AUD01_0014Audience already exists.

Examples

Request:

POST {uri-prefix}/audiences

{
  "clientId":"345343",
  "accountType":"DATA_PROVIDER_CLIENT",
  "name":"Travel Enthusiasts",
  "description":"test",
  "dataProviderId":"383",
  "definition":"Male AND AGE < 24 AND EDU=PHOTO",
  "providerAudienceId":"7",
  "transferCode":"14232323"
}

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

Attachments

    Outcomes