Reseller Management API

Yahoo Native resellers are able to create and manage advertiser accounts using the Yahoo Native 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 Yahoo Native 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, speak to your Yahoo Ad Tech acouunt representative about whitelisting for this feature.

Important

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, to read the targeting settings for that ad group you’ll need to make the following GET call: https://api.gemini.yahoo.com/v4/rest/targetingattribute?advertiserId=222&parentId=111&parentType=ADGROUP

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

budget

Budget amounts are interpreted in advertiser currency.

long

Optional

Optional

budgetType

The allowed budget types are NONE, TOTAL and MONTHLY.

string

Optional

Optional

previousBudget

The budget that is currently running and will expire in one day. This is a READ-ONLY parameter.

long

Optional

Optional

previousBudgetType

The budget that is currently running and will expire in one day. This is a READ-ONLY parameter.

string

Optional

Optional

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 Native & Search 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"
      }
  ]
}

Read specific advertiser budget data

Method: To retrieve data for a specific advertiser budget, make a GET call with the parameters in the table below:

Example: GET call to retrieve an advertiser budget:

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


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

{
  "errors": null,
      "response": {
            "id": 1365112,
        "budget": 11,
        "budgetType": "TOTAL",
        "previousBudget": null,
        "previousBudgetType": "NONE"
   }
}

Response: The advertiser budget associated with the given ID.

Update existing advertiser budget

Method: To update one or more existing advertiser budgets, make a PUT call to the Advertiser endpoint with one or more budget parameters. Specify the fields to update; please note that id and budgetType are the only required parameters, all other fields are optional. The result will be the list of updated advertiser budgets. The allowed budget types are NONE, TOTAL, MONTHLY.

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

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

Data passed

      {
              "id":1365112,
              "budgetType":"TOTAL",
              "budget":11
      }

Example response

      {
          "errors": null,
              "response": {
                    "id": 1365112,
                "budget": 11,
                "budgetType": "TOTAL"
           }
      }

Note

Budget amounts are interpreted in advertiser currency.