Conversion Rule Audience

This article describes resources and services that enable you to read, create, and update conversion rule audiences.

Overview

A conversion rule audience enables you to target custom audiences based on conversion rules. A conversion rule audience is built from Dot tags created via the Beacons API. Before you set up conversion rules for your audience, create the Dot tags on which the audience will be built.

Note

You can only build a conversion rule audience for one advertiser at a time, not for an entire seat.

Endpoint

You can read, update, and create conversion rule audiences via the conversion rule resource.

/traffic/audiences/conversion_rule
  • Use the GET method to read conversion rule audience data.
  • Use the POST method to create new conversion rule audiences.
  • Use the PUT method to update existing conversion rule audiences.

Resources

The conversion_rule resource defines a conversion rule audience. The conversion_rule resource contains the following fields:

Table 30 Conversion Rule Audience Resource Fields
Field Description Data Type Add Update
id Specifies the audience ID. integer N/A Required
name Specifies the name of the audience. string Required Optional
status

Specifies the current status of the audience. By default, ACTIVE. Options include:

  • If ACTIVE, the audience can be targeted.
  • If INACTIVE, the audience cannot be targeted.
string Optional Optional
accountId

Specifies the advertiser ID.

If specified, the conversion rule audience is tied to a specific advertiser and can only be used in that advertiser’s campaigns. To learn more, see Advertisers.

string Required Required
pixelRuleId Specifies the pixel rule ID of the associated pixel rule. integer Required N/A
createdAt Read-only field that specifies the date and time the audience was created. string N/A N/A
pixelRuleId Read-only field that specifies the pixel rule name of the associated pixel rule. string N/A N/A
pixelRuleSize Read-only field that specifies the size of the associated pixel rule. string N/A N/A

Read Conversion Rule Audiences by ID

Retrieves data for a specified conversion rule audience.

GET /traffic/audiences/conversion_rule/{id}?accountId={accountId}

Parameters

The resource takes two parameters. Both are required.

Table 31 Read Audience by ID Parameters
Parameter Parmameter Type Description Data Type Required
id path Specifies the audience ID. integer Y
accountId query Specifies the advertiser’s account ID. integer Y

The response will be the Conversion Rule Audience segment associated with the given ID.

Example Request

GET https://dspapi.admanagerplus.yahoo.com/traffic/audiences/audiences/conversion_rule/50259012?accountId=1356341

Example Response

The response returns the conversion rule audience associated with the specified ID.

{
  "response": {
    "status": "ACTIVE",
    "id": 50259012,
    "name": "HP Conversion Audience",
    "accountId": 1356341,
    "pixelRuleName": "HP Conversion",
    "pixelRuleId": 10055198,
    "pixelRuleSize": 58888
  },
  "errors": null,
  "timeStamp": "2017-10-20T19:04:17Z"
}

Read Conversion Rules by Query

Retrieves a list of conversion rules for specific advertiser.

GET /traffic/audiences/conversion_rule/lookups?accountId={accountId}&page={page}&limit={limit}&sort={sort}&dir={dir}&query={query}

Parameters

Table 32 Read Covnersion Rule Audience by Query
Name Type Description Data Type Required
accountId query Specifies the advertisers account ID. integer Y
page query Specifies the page number. integer N
limit query Specifies the total number of items to return. Maximum value is 100. integer N
sort query Specifies the field on which to sort the returned data. string N
dir query Specifies the sort direction. Valude values are ASC, DESC. string N
query query Specifies the search terms. Use URL encoding conversions (i.e. a space should be relaced with a + or %20). string N

The response will be a list of matching conversion rules with the number of unique users (audience size) for each entry.

Example Request

GET https://dspapi.admanagerplus.yahoo.com/traffic/audiences/conversion_rule/lookups?accountId=1356341&page=1&limit=3&dir=desc&sort=name

Example Response

{
  "response": [
    {
      "id": 10023297,
      "name": "結帳頁面",
      "uniqueUserCount": 2
    },
    {
      "id": 152028,
      "name": "Z_Flow_PxlZzaS8vG1Uu",
      "uniqueUserCount": 0
    },
    {
      "id": 149474,
      "name": "Z_Flow_PxlZwQx1KmESq",
      "uniqueUserCount": 0
    }
  ]
}

Update Conversion Rule Audiences

To update an existing Conversion Rule Audience, make a PUT call with a payload body and id parameter. The response will be the updated Audience.

Note

You cannot change your conversion rule audiences once you create them. You can only update a conversion rule name or its status.

PUT /traffic/audiences/conversion_rule/{id}

Partial update is supported; fields that are either not passed or passed as null will be ignored during update.

Parameters

The audience ID is specified in the path of the endpoint. All other parameters are specified in the body of the application/json payload.

Table 33 Update Conversion Rule Audience Parameters
Parameter Parameter Type Description Data Type Required
id body Specifies the audience ID of the conversion rule audience. string Required
name body Specifies the name of the audience. string Optional
status body

Specifies the current status of the audience. By default, ACTIVE. Options include:

  • If ACTIVE, the audience can be targeted.
  • If INACTIVE, the audience cannot be targeted.
string Optional
accountId body

Specifies the advertiser ID.

If specified, the conversion rule audience is tied to a specific advertiser and can only be used in that advertiser’s campaigns. To learn more, see Advertisers.

string Required

Example Request

The audience ID is specified in the path of the endpoint.

PUT https://dspapi.admanagerplus.yahoo.com/traffic/audiences/conversion_rule/50259012

All other parameters are specified in the body of the application/json payload.

{
  "name": "audienceTest_2",
  "accountId": 1356341
}

Example Response

{
  "response": {
    "status": "ACTIVE",
    "id": 50259012,
    "name": "audienceTest_2",
    "accountId": 1356341,
    "pixelRuleName": "HP Conversion",
    "pixelRuleId": 10055198,
    "pixelRuleSize": 58888
  },
  "errors": null,
  "timeStamp": "2017-10-20T19:04:17Z"
}

Create Conversion Rule Audiences

Creates a new conversion rule audience.

POST  /traffic/audiences/conversion_rule

Note

Conversion rule audiences take about 24 hours to populate.

Parameters

All parameters are specified in the body of the application/json payload.

Table 34 Create Conversion Rule Audience Parameters
Parameter Parameter Type Description Data Type Required
name body Specifies the name of the audience. string Required
status body

Specifies the current status of the audience. By default, ACTIVE. Options include:

  • If ACTIVE, the audience can be targeted.
  • If INACTIVE, the audience cannot be targeted.
string Optional
accountId body

Specifies the advertiser ID.

If specified, the conversion rule audience is tied to a specific advertiser and can only be used in that advertiser’s campaigns. To learn more, see Advertisers.

string Required
pixelRuleId body Specifies the pixel rule ID of the associated conversion rule. integer Required

Example Request

POST https://dspapi.admanagerplus.yahoo.com/traffic/audiences/conversion_rule

All parameters are specified in the body of the application/json payload.

{
  "name": "Create_Conversion_Rule",
  "accountId": 1356341,
  "pixelRuleId": 10067237,
  "status": "ACTIVE"
}

Example Response

{
  "response": {
    "status": "ACTIVE",
    "id": 50389217,
    "name": "Create_Conversion_Rule",
    "accountId": 1356341,
    "pixelRuleName": "FH P2_Player-JoinPublic",
    "pixelRuleId": 10067237,
    "pixelRuleSize": 2605
  },
  "errors": null,
  "timeStamp": "2017-10-11T00:33:54Z"
}

Delete Conversion Rule Audiences

The DSP Traffic API does not supporting deleting audiences.