Create Shared Sets

Overview

Shared sets are objects created on the advertiser account level, using the shared set endpoint. The SharedSetService provides methods for creating, updating and retrieving shared sets. Once created, shared sets can be linked to any campaign or ad group.

For example, you can create a shared set of negative keywords and populate the set with a list of keywords you may wish to exclude, using the sharednegativekeyword API. Refer to Populate Shared Sets for details on how to accomplish this task.

You can also associate the shared set to a campaign, using the campaignsharedset API. Refer to Associate Shared Sets to a Campaign for details on how to accomplish this task.

Fields

Shared Set contains the following fields:

Name Description Type Add Update
id The ID of the shared set. long required required
advertiserId The ID of the advertiser. long required optional
status The status of the shared set. Valid values: ACTIVE, DELETED. enum required optional
name The title of the shared set. string required optional
type The type of the shared set. Currently, only NEGATIVE_KEYWORD is supported. enum required optional
memberCount The number of entities in the shared set. integer read-only read-only
referenceCount The number of campaigns that actively use the shared set. integer read-only read-only

Endpoint

Resource URI

https://api.gemini.yahoo.com/v3/rest/sharedset/

Example Representations

Shared Set

{
  "name": "My Shared Set",
  "type": "NEGATIVE_KEYWORD",
  "memberCount": 100,
  "referenceCount": 0,
  "status": "ACTIVE",
  "id": 103002,
  "advertiserId": 925746
}

Shared Set Array

[
 {
  "name": "My Shared Set",
  "type": "NEGATIVE_KEYWORD",
  "memberCount": 100,
  "referenceCount": 0,
  "status": "ACTIVE",
  "id": 103002,
  "advertiserId": 925746
 },
 {
  "name": "My Shared Set #2",
  "type": "NEGATIVE_KEYWORD",
  "memberCount": 80,
  "referenceCount": 0,
  "status": "ACTIVE",
  "id": 103003,
  "advertiserId": 925746
 }
]

Shared Set Response

{
"errors": null,
"response": [
   {
      "name": "My Shared Set",
      "type": "NEGATIVE_KEYWORD",
      "memberCount": 100,
      "referenceCount": 0,
      "status": "ACTIVE",
      "id": 103002,
      "advertiserId": 925746
   }
  ]
}

Operations

Read

Method: To retrieve data for a specific shared set, make a GET call with the ID parameter:

GET https://api.gemini.yahoo.com/v3/rest/sharedset/1234

The response will be the shared set associated with the id:

{
  "errors": null,
  "response": [
     {
       "name": "My Shared Set",
        "type": "NEGATIVE_KEYWORD",
        "memberCount": 100,
        "referenceCount": 0,
        "status": "ACTIVE",
        "id": 103002,
        "advertiserId": 925746
     }
  ]
}

Method: To retrieve data for a shared set with multiple IDs, make a GET call with the ID parameter:

GET https://api.gemini.yahoo.com/v3/rest/sharedset?id=1234&id=5678

    The response will be the shared set associated with multiple ids:

    {
      "errors": null,
      "response": [
         {
           "name": "My Shared Set",
            "type": "NEGATIVE_KEYWORD",
            "memberCount": 100,
            "referenceCount": 0,
            "status": "ACTIVE",
            "id": 103002,
            "advertiserId": 925746
         },
         {
           "name": "My Shared Set #2",
            "type": "NEGATIVE_KEYWORD",
            "memberCount": 100,
            "referenceCount": 0,
            "status": "ACTIVE",
            "id": 103003,
            "advertiserId": 925746
         }
      ]
    }

Read data for a filtered list of a shared set

Method: To retrieve data for a filtered list of a shared set, make a GET call with the following parameters:

Name Description Type
mr The maximum number of rows to retrieve. int
si The start index or the first element to retrieve. int
advertiserId The ID of the advertiser to filter the shared sets by. long
status The shared set status to filter by. enum
type The shared set type to filter by. enum

Important

Only one advertiserId parameter is allowed to be passed in as a query parameter for all filtered lists of shared set calls.

Endpoint

Resource URI

https://api.gemini.yahoo.com/v3/rest/sharedset?advertiserId=1111

Create a new shared set

Method: To create a new shared set, make a POST call. The response will be the newly created shared set.

For example:

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

Update an existing shared set

Method: To update an existing shared set, make a PUT call. The result will be the list of the updated shared set.

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

Delete a shared set

Method: To delete a shared set, make a PUT call.

Note

In v2, the DELETE operation is supported for both single and multiple ids.

For example:

DELETE  https://api.gemini.yahoo.com/v3/rest/sharedset/1234
DELETE  https://api.gemini.yahoo.com/v3/rest/sharedset?id=1234&id=5678

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

{
  "status": "DELETED",
  "id": 103002
}