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 |
---|---|---|---|---|
|
The ID of the advertiser to retrieve. |
long |
NA |
Required |
|
The name of the advertiser. |
string |
Required |
Optional |
|
This field defaults to “ADVERTISER” and is read-only. |
enum |
Read-only |
Read-only |
|
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 |
|
The timezone of the advertiser. Defaults to the timezone of the parent reseller. |
enum |
Optional |
Optional |
|
The status of the advertiser. Can be either “ACTIVE”, “PAUSED” or “DELETED”. This field defaults to “ACTIVE”. |
enum |
Optional |
Optional |
|
The currency of the advertiser. Defaults to the currency of the parent reseller. |
enum |
Read-only |
Read-only |
|
The booking country of the advertiser. Defaults to the booking country of the parent reseller. |
enum |
Read-only |
Read-only |
|
The billing country of the advertiser. Defaults to the billing country of the parent reseller. |
enum |
Read-only |
Read-only |
|
The language of the advertiser. Defaults to the language of the parent reseller. |
enum |
Read-only |
Read-only |
|
Budget amounts are interpreted in advertiser currency. |
long |
Optional |
Optional |
|
The allowed budget types are NONE, TOTAL and MONTHLY. |
string |
Optional |
Optional |
|
The budget that is currently running and will expire in one day. This is a READ-ONLY parameter. |
long |
Optional |
Optional |
|
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 |
---|---|---|
|
The ID of the advertiser to retrieve. |
long |
|
The maximum number of rows to retrieve. This value should not be greater than 500. |
int |
|
The start index or the first element to retrieve. |
int |
|
Allows getting all managed accounts under a specific reseller. Accepts the id of a reseller. |
long |
|
The type of advertiser account to retrieve. Can be either RESELLER or ADVERTISER. |
enum |
|
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 |
---|---|
|
The ID of the advertiser to delete. |
|
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.