Search Keyword Audiences (SRT)

Overview

A search keyword audience is populated with Yahoo Search users who search for certain words or phrases. You can include or exclude users who search for keywords you specify.

You can build search keyword audiences to share across your seat, or for individual advertisers.

Endpoint

https://dspapi.admanagerplus.yahoo.com/traffic/audiences/srt

Fields

The SRT object contains the following fields:

Name Description Type Add Update
id ID of the audience segment. integer N/A Required
name Name of the segment. text Required Optional
retention_days

Number of days to count back from today in determining if the keyword search qualifies the user to be included in the audience.

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7 - Default Value
  • 15
  • 30
integer Optional Optional
status

Current status of the segment.

  • ACTIVE - (Default Value) Active.
  • INACTIVE - Inactive
text Optional Optional
matchType

Type of site list.

  • EXACT - (Default Value) Match only keywords that are exactly the same.
  • BROAD - Expand the keyword seed list by generating new keywords and keyword phrases that are semantically similar.
text Optional Optional
isGlobal

Indicate whether the segment is at Seat or Advertiser level.

  • true - Seat-level audience can be used for all the advertisers across your seat. Ensure that accountId is null to create a seat-level audience.
  • false - Advertiser-level audience is available for a single adversier. You must provide an accountId for this option.
text Required Required
accountId Advertiser/account ID to associate this segment with when creating or updating an advertiser-level audience. (1) Required when isGlobal is false. (2) Required when updating an existing advertiser-level audience. Refer to Advertisers. integer Required (1) Required (2)
keywords Array containing text keywords. Use this to include users who search for specific keywords. array Required Required
excludeKeywords Array containing text keywords. Use this to exclude people who search for certain keywords. To remove any existing values, send an empty array. array Optional Optional
createdAt (Read-Only) Creation timestamp. datetime N/A N/A

Read Seat-Level Audience (Single)

To retrieve data for a specific Seat-Level Search Keyword Audience (SRT), make a GET call with the id parameter.

GET https://dspapi.admanagerplus.yahoo.com/traffic/audiences/srt/{id}
Name Description Type Required?
id Audience / Segment ID integer Y

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

Example Request

GET https://dspapi.admanagerplus.yahoo.com/traffic/audiences/srt/50299597

Example Response

{
  "response": {
    "matchType": "EXACT",
    "id": 50299597,
    "name": "TestSegment_TR46",
    "keywords": [
      "keyword1",
      "keyword2"
    ],
    "excludeKeywords": [
      "exclude_keyword1"
    ],
    "createdAt": "2017-08-09",
    "status": "ACTIVE",
    "isGlobal": true,
    "retention_days": 90
  },
  "errors": null,
  "timeStamp": "2017-08-09T18:06:19Z"
}

Read Advertiser-Level Audience (Single)

To retrieve data for a specific Advertiser-Level Search Keyword Audience (SRT), make a GET call with the parameters specified below.

GET https://dspapi.admanagerplus.yahoo.com/traffic/audiences/srt/{id}?accountId={accountId}
Name Description Type Required?
id Audience / Segment ID integer Y
accountId Account or Advertiser ID integer Y

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

Example Request

GET https://dspapi.admanagerplus.yahoo.com/traffic/audiences/srt/50301215?accountId=1356341

Example Response

{
  "response": {
    "matchType": "EXACT",
    "id": 50301215,
    "name": "TestSegment_TR7507",
    "accountId": 1356341,
    "keywords": [
      "keyword1",
      "keyword2"
    ],
    "excludeKeywords": [
      "exclude_keyword1"
    ],
    "createdAt": "2017-08-11",
    "status": "ACTIVE",
    "isGlobal": false,
    "retention_days": 7
  },
  "errors": null,
  "timeStamp": "2017-08-11T18:08:37Z"
}

Update Audience

To update an existing Search Keyword Audience (SRT), make a PUT call with a payload body and id parameter. The response will be the updated Audience.

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

Note When updating an Advertiser-Level audience, isGlobal and accountId fields are required.

PUT https://dspapi.admanagerplus.yahoo.com/traffic/audiences/srt/{id}
Name Description Type Required?
id Audience / Segment ID integer Y

Example Request

PUT https://dspapi.admanagerplus.yahoo.com/traffic/audiences/srt/50300847

Example Payload (Seat-Level)

{
  "isGlobal": true,
  "keywords": [
    "keyword124",
    "keyword2"
  ]
}

Example Response (Seat-Level)

{
  "response": {
    "matchType": "EXACT",
    "id": 50300847,
    "name": "TestSegment_TR60",
    "keywords": [
      "keyword124",
      "keyword2"
    ],
    "excludeKeywords": [
      "exclude_keyword1"
    ],
    "createdAt": "2017-08-10",
    "status": "ACTIVE",
    "isGlobal": true,
    "retention_days": 90
  },
  "errors": null,
  "timeStamp": "2017-08-11T06:53:40Z"
}

Example Payload (Advertiser-Level)

{
  "name": "TestSegment_TR7507",
  "retention_days": 7,
  "keywords": [
    "keyword1",
    "keyword2"
  ],
  "status": "ACTIVE",
  "isGlobal": false,
  "accountId": 1356341
}

Example Response (Advertiser-Level)

{
  "response": {
    "matchType": "EXACT",
    "id": 50300835,
    "name": "TestSegment_TR7507",
    "accountId": 1356341,
    "keywords": [
      "keyword1",
      "keyword2"
    ],
    "createdAt": "2017-08-10",
    "status": "ACTIVE",
    "isGlobal": false,
    "retention_days": 7
  },
  "errors": null,
  "timeStamp": "2017-08-11T06:28:54Z"
}

Create Audience

To create a new Search Keyword Audience (SRT), make a POST call with a payload body. The response will be the newly created Audience.

Example Request

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

Example Payload (Seat-Level)

{
  "name": "TestSegment_TR46",
  "keywords": [
    "keyword1",
    "keyword2"
  ],
  "excludeKeywords": [
   "exclude_keyword1"
  ],
  "isGlobal": true
}

Example Response (Seat-Level)

{
  "response": {
    "matchType": "EXACT",
    "id": 50299597,
    "name": "TestSegment_TR46",
    "keywords": [
      "keyword1",
      "keyword2"
    ],
    "excludeKeywords": [
      "exclude_keyword1"
    ],
    "createdAt": "2017-08-09",
    "status": "ACTIVE",
    "isGlobal": true,
    "retention_days": 90
  },
  "errors": null,
  "timeStamp": "2017-08-09T17:50:05Z"
}

Example Payload (Advertiser-Level)

{
  "name": "TestSegment_TR52",
  "keywords": [
    "keyword1",
    "keyword2"
  ],
  "excludeKeywords": [
   "exclude_keyword1"
  ],
  "isGlobal": false,
  "accountId": 1356341
}

Example Response (Advertiser-Level)

{
  "response": {
    "matchType": "EXACT",
    "id": 50300102,
    "name": "TestSegment_TR52",
    "accountId": 1356341,
    "keywords": [
      "keyword1",
      "keyword2"
    ],
    "excludeKeywords": [
      "exclude_keyword1"
    ],
    "createdAt": "2017-08-10",
    "status": "ACTIVE",
    "isGlobal": false,
    "retention_days": 90
  },
  "errors": null,
  "timeStamp": "2017-08-10T03:46:38Z"
}

Delete Audience

Audience deletion is not supported by the API.