Reseller Management API

Gemini resellers are able to create and manage advertiser accounts using the Gemini Advertiser service. Advertiser accounts created by a reseller do not carry billing settings, as their spend is aggregated to their parent reseller.

Resellers are provided with additional functionality for managing their accounts, but only within the advertiser object. As a reseller, you may still use all other RESTful objects in the Gemini API when making campaign management and reporting calls on behalf of your managed advertisers. This additional functionality enables you to make GET, POST and PUT calls to the advertiser endpoint in order to create, manage and retrieve advertiser data for your child accounts.

If you require reseller functionality, please speak to your Yahoo representative about whitelisting for this feature.

Fields

The Advertiser object contains the following fields:

Name Description Type Add Update
id The ID of the advertiser to retrieve. long NA Required
advertiserName The name of the advertiser. string Required Optional
type This field defaults to “ADVERTISER” and is read-only. enum Read-only Read-only
managedBy This field indicates that the advertiser account has a managing entity that is authorized to perform actions on their behalf. The value should be the id of the reseller that is creating the account, and is immutable once set. long Required Read-only
timezone The timezone of the advertiser. Defaults to the timezone of the parent reseller. enum Optional Optional
status The status of the advertiser. Can be either “ACTIVE”, “PAUSED” or “DELETED”. This field defaults to “ACTIVE”. enum Optional Optional
currency The currency of the advertiser. Defaults to the currency of the parent reseller. enum Read-only Read-only
bookingCountry The booking country of the advertiser. Defaults to the booking country of the parent reseller. enum Read-only Read-only
billingCountry The billing country of the advertiser. Defaults to the billing country of the parent reseller. enum Read-only Read-only
language The language of the advertiser. Defaults to the language of the parent reseller. enum Read-only Read-only

Endpoint

Resource URI

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

Example Representations

Advertiser

{
  "type": "ADVERTISER",
  "currency": "USD",
  "bookingCountry": "US",
  "billingCountry": "US",
  "language": "en",
  "timezone": "America/New_York",
  "status": "ACTIVE",
  "id": 6410,
  "managedBy": 6659,
  "advertiserName": "one of my managed accounts"
}

Advertiser Array

[
  {
      "type": "ADVERTISER",
      "currency": "USD",
      "bookingCountry": "US",
      "billingCountry": "US",
      "language": "en",
      "timezone": "America/New_York",
      "status": "ACTIVE",
      "id": 6410,
      "managedBy": 6659,
      "advertiserName": "one of my managed accounts"
  },
  {
      "type": "ADVERTISER",
      "currency": "USD",
      "bookingCountry": "US",
      "billingCountry": "US",
      "language": "en",
      "timezone": "America/New_York",
      "status": "ACTIVE",
      "id": 6415,
      "managedBy": 6659,
      "advertiserName": "another one of my managed accounts"
  }
]

Advertiser Response

{
  "errors": null,
  "response": [
      {
          "type": "ADVERTISER",
          "currency": "USD",
          "bookingCountry": "US",
          "billingCountry": "US",
          "language": "en",
          "timezone": "America/New_York",
          "status": "ACTIVE",
          "id": 6410,
          "managedBy": 6659,
          "advertiserName": "one of my managed accounts"
      }
  ]
}

Operations

Read specific advertiser data

Method: To retrieve data for a specific advertiser or for a list of advertisers, make a GET call with the id parameter.

Example: GET call to retrieve an advertiser:

https://api.gemini.yahoo.com/v3/rest/advertiser/6410

The response will be the advertiser associated with the given id:

{
  "errors": null,
  "response": {
      "type": "ADVERTISER",
      "currency": "USD",
      "bookingCountry": "US",
      "billingCountry": "US",
      "language": "en",
      "timezone": "America/New_York",
      "status": "ACTIVE",
      "id": 6410,
      "managedBy": 6659,
      "advertiserName": "sample managed acct"
  }
}

Example: GET call to retrieve a list of advertisers:

https://api.gemini.yahoo.com/v3/rest/advertiser/?id=6410&id=6415

Response: The advertisers associated with the given ids:

[
  {
      "errors": null,
      "response": [
          {
            "type": "ADVERTISER",
            "currency": "USD",
            "bookingCountry": "US",
            "billingCountry": "US",
            "language": "en",
            "timezone": "America/New_York",
            "status": "ACTIVE",
            "id": 6410,
            "managedBy": 6659,
            "advertiserName": "one of my managed accounts"
          },
          {
            "type": "ADVERTISER",
            "currency": "USD",
            "bookingCountry": "US",
            "billingCountry": "US",
            "language": "en",
            "timezone": "America/New_York",
            "status": "ACTIVE",
            "id": 6415,
            "managedBy": 6659,
            "advertiserName": "another one of my managed accounts"
          }
      ]
  }
]

Read data for filtered list of advertisers

Method: To retrieve data for a filtered list of advertisers, make a GET call with the parameters in the table below:

Name Description Type
id The ID of the advertiser to retrieve. long
mr The maximum number of rows to retrieve. This value should not be greater than 500. int
si The start index or the first element to retrieve. int
managedBy Allows getting all managed accounts under a specific reseller. Accepts the id of a reseller. long
type The type of advertiser account to retrieve. Can be either RESELLER or ADVERTISER. enum
nameContains Any part of the advertiser name string

Note

The query parameter nameContains, which is new in the v2 Gemini API, enables Resellers to retrieve advertisers within a reseller account by name. An example GET call, using the nameContains parameter:

https://api.gemini.yahoo.com/v3/rest/advertiser?si=0&mr=25&managedBy=45820&nameContains=SEM-

Example: GET call for a filtered list of advertisers:

https://api.gemini.yahoo.com/v3/rest/advertiser/?si=0&mr=3

Response: The list of advertisers matching the given filter.

{
  "errors": null,
  "response": [
      {
        "type": "ADVERTISER",
        "currency": "USD",
        "bookingCountry": "US",
         "billingCountry": "US",
        "language": "en",
        "timezone": "America/New_York",
        "status": "ACTIVE",
        "id": 10,
        "managedBy": 5,
        "advertiserName": "managed advertiser 1"
      },
      {
        "type": "ADVERTISER",
       "currency": "USD",
       "bookingCountry": "US",
       "billingCountry": "US",
       "language": "en",
       "timezone": "America/New_York",
       "status": "ACTIVE",
       "id": 11,
       "managedBy": 5,
       "advertiserName": "managed advertiser 2"
      },
      {
        "type": "ADVERTISER",
        "currency": "USD",
        "bookingCountry": "US",
        "billingCountry": "US",
        "language": "en",
        "timezone": "America/New_York",
        "status": "ACTIVE",
        "id": 104,
        "managedBy": 5,
        "advertiserName": "managed advertiser 3"
      }
  ]
}

Read campaign data for child accounts

When making GET calls to retrieve objects that belong to child accounts, the advertiserId parameter must be provided. For example, if you have an adgroup 111 under a managed advertiser with an id 222, in order to read the targeting settings for that ad group you will need to make the following GET call:

https://api.gemini.yahoo.com/v4/rest/targetingattribute?advertiserId=222&parentId=111&parentType=ADGROUP

Update existing advertiser accounts

Method: To update existing advertisers, make a PUT call to the advertiser endpoint with one or more advertiser objects. Specify the fields to update; please note that id is the only required parameter, all other fields are optional. The response will be the list of updated advertisers. Partial update is supported; fields that are either not passed or passed as null will be ignored for the update.

For example, in order to update the status for an existing advertiser:

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

Data passed:

{
  "id": 104,
  "status": "PAUSED"
}

Response:

{
  "errors": null,
  "response": [
      {
          "type": "ADVERTISER",
          "currency": "USD",
          "bookingCountry": "US",
          "billingCountry": "US",
          "language": "en",
          "timezone": "America/New_York",
          "status": "PAUSED",
          "id": 104,
          "managedBy": 6659,
          "advertiserName": "one of my managed accounts"
      }
   ]
}

Create a new advertiser account

Method: To create a new advertiser, make a POST call to the advertiser endpoint. The response will be the newly created advertiser. Batch create is supported; either an advertiser or an advertiser array can be passed.

Here is an example:

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

Data passed (note that fields that default to the reseller attributes are not passed):

 [
  {
      "timezone": "America/New_York",
      "status": "ACTIVE",
      "advertiserName": "creating a managed account",
      "managedBy": 23
  },
  {
      "timezone": "America/Los_Angeles",
      "status": "ACTIVE",
      "advertiserName": "creating another managed account",
      "managedBy": 23
  }
]

Response:

[
  {
     "errors": null,
     "response": [
         {
           "type": "ADVERTISER",
           "currency": "USD",
           "bookingCountry": "US",
           "billingCountry": "US",
           "language": "en",
           "timezone": "America/Los_Angeles",
           "status": "ACTIVE",
           "id": 9000,
           "managedBy": 23,
           "advertiserName": "creating a managed account"
         },
         {
           "type": "ADVERTISER",
           "currency": "USD",
           "bookingCountry": "US",
           "billingCountry": "US",
           "language": "en",
           "timezone": "America/New_York",
           "status": "ACTIVE",
           "id": 9001,
           "managedBy": 23,
           "advertiserName": "creating another managed account"
         }
     ]
  }
]

Delete an advertiser account

Method: To delete an advertiser account, make a PUT call with the Advertiser object. Batch delete is supported; either an advertiser or an advertiser array can be passed.

The following needs to be passed:

Name Description
id The ID of the advertiser to delete.
status The status of the advertiser set to DELETED in order to delete the advertiser account.

Important

API calls involving Reseller accounts need to add the advertiserId parameter on all calls that reference ad objects, i.e., Ads, Ad Groups, Campaigns, Keywords, Ad Extensions and Targeting.

For example:

https://api.gemini.yahoo.com/v3/rest/adgroup?campaignId=12345678&advertiserId=112233

Note

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

Example:

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

Data passed:

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

Response:

{
  "errors": null,
  "response": [
      {
        "type": "ADVERTISER",
        "currency": "USD",
        "bookingCountry": "US",
        "billingCountry": "US",
        "language": "en",
        "timezone": "America/New_York",
        "status": "DELETED",
        "id": 104,
        "managedBy": 6659,
        "advertiserName": "one of my managed accounts"
      }
  ]
}