Conversion rule audiences

Conversion rule audiences allow advertisers to create custom audiences from specified conversion rules. You can create conversion rule audiences either to target or exclude converted users for a specific number of days after conversion. (The maximum is 30 days.)

Important

Conversion rule audiences can only be created from conversion rules.

Fields

Conversion rule audiences have the following fields:

Name

Description

Type

Add

Update

id

The unique identifier of the audience.

long

N/A

Required

advertiserId

The id of the advertiser that owns the audience.

long

Required

N/A

name

The name of the audience segment. Maximum is 255 characters.

string

Required

Optional

description

A description for the segment. Maximum is 255 characters.

string

Optional

Optional

type

Must be set to CONVERSIONRULE.

enum

Required

Read-Only

conversionRuleId

The ID of the conversion rule.

long

Required

Read-Only

retentionDays

Number of days the user will remain in an audience. Accepts values between 1 and 30 and will default to 30 if not specified.

int

Optional

Optional

tagId

The id of the tag whose events define the audience. (This must match conversion conversionRuleId tagId).

string

Required

Read-Only

cnt24h

Unique user count for the last 24 hours.

long

Read-Only

Read-Only

cnt30d

Unique user count for the last 30 days.

long

Read-Only

Read-Only

status

The status of the segment. Can be ACTIVE or DELETED, and is set to ACTIVE by default.

enum

Optional

Optional

Create a new audience

Method: To create a new audience, make a POST call to the audience endpoint with the required fields. Batch create is supported. The response will be the newly created audience, or a list of multiple new audiences if an array is passed.

For example:

POST https://api.gemini.yahoo.com/v3/rest/audience

  Data passed

      {
          "advertiserId": "1530348",
          "retentionDays": 13,
          "tagId":"10034962",
          "name": "My conversion audience",
          "conversionRuleId": 10068488,
          "type": "CONVERSIONRULE"
      }



      Example response

      {
          "errors": null,
          "timestamp": "2017-11-20 22:23:23",
          "response": {
              "type": "CONVERSIONRULE",
              "id": 50389642,
              "advertiserId": 1530348,
              "name": "My conversion audience",
              "description": null,
              "retentionDays": 13,
              "status": "ACTIVE",
              "createdDate": null,
              "lastUpdateDate": null,
              "conversionRuleId": 10068488,
              "tagId": 10034962
          }
      }

Important

Your conversion audience will be available for targeting immediately, but it may take up to one day (24 hours) for the audience to finish populating with all the relevant users. You should expect limited delivery if you target this segment during this time window.

Update existing audiences

Method: To update one or more existing audiences, make a PUT call with one or more audience objects. Specify the fields to update; note that id and type are the only required parameters, all other fields are optional. The result will be the list of updated objects. Partial update is supported; fields that are either not passed or passed as null will be ignored for the update.

For example:

PUT https://api.gemini.yahoo.com/v3/rest/audience

  Data passed

      {
      "advertiserId": "1530348",
      "id": 50389647,
      "type":"CONVERSIONRULE",
      "retentionDays": 30
      }



      Example response

      {
          "errors": null,
          "timestamp": "2017-11-20 22:34:15",
          "response": {
              "type": "CONVERSIONRULE",
              "id": 50389647,
              "name": "My conversion audience 1",
              "retentionDays": 30,
              "status": "ACTIVE",
              "conversionRuleId": "10068488",
              "tagId": "10034962"
          }
      }

Delete an audience

Method: To delete an audience, make a PUT call with the audience object. Batch delete is supported: either a single object or an array can be passed. The following parameters are required:

Name

Description

id

The id of the object to delete.

status

The status of the object to be deleted.

For example:

PUT https://api.gemini.yahoo.com/v3/rest/audience
DELETE https://api.gemini.yahoo.com/v3/rest/audience/{id}
DELETE https://api.gemini.yahoo.com/v3/rest/audience?id=123&id=1234&...

Data passed

PUT https://api.gemini.yahoo.com/v3/rest/audience


      {
          "status": "DELETED",
          "type": "CONVERSIONRULE",
          "id": 50389647
      }



      Example response

      {
          "errors": null,
          "timestamp": "2017-11-20 22:34:15",
          "response": {
              "type": "CONVERSIONRULE",
              "id": 50389647,
              "name": "My conversion audience 1",
              "retentionDays": 30,
              "status": "DELETED",
              "conversionRuleId": "10068488",
              "tagId": "10034962"
          }
      }

Target a campaign to a My Audience segment

Once you have created custom audience segments, you can target Native & Search campaigns and ad groups to serve to these audiences using the TargetingAttribute service, passing in the audience id in the value field.

For example:

POST https://api.gemini.yahoo.com/v3/rest/targetingattribute

   Data passed

      {
          "value": "2222",
          "type": "MY_AUDIENCE",
          "status": "ACTIVE",
          "advertiserId": 123,
          "parentType": "CAMPAIGN",
          "parentId": 789,
          "exclude": "FALSE",
          "bidModifier": null
      }


      Example response

      {
          "errors": null,
          "response": {
              "id": 3273448769,
              "value": "2222",
              "type": "MY_AUDIENCE",
              "status": "ACTIVE",
              "advertiserId": 123,
              "parentType": "CAMPAIGN",
              "parentId": 789,
              "exclude": "FALSE",
              "bidModifier": null
          }
      }