Version:

Table of Contents

Introduction 1
Account Organization/Hierarchy 1
Accessing the SOAP API 2
Services 3
Complex Types 12

Introduction

Account Organization/Hierarchy

Accessing the SOAP API

Services

AdGroup

WSDL: AdGroup.wsdl  

Provides a set of methods for retrieving, creating and updating ad groups

  • AdGroupGetAdGroup ( int $advertiser_id, int $ad_group_id )
    Get an ad group by its ad group id
    int $advertiser_id ID of the advertiser that owns the ad group
    int $ad_group_id ID of the ad group to return
  • AdGroup[]GetAdGroupsByCampaign ( int $advertiser_id, int[] $campaign_ids )
    Get a list of ad groups by their campaign id
    int $advertiser_id ID of the advertiser that owns the ad group
    int[] $campaign_ids Array of campaign IDs whose ad groups will be returned
  • AdGroup[]GetActiveAdGroupsByCampaign ( int $advertiser_id, int[] $campaign_ids )
    Get a list of all active ad groups in a given campaign
    int $advertiser_id ID of the advertiser that owns the ad group
    int[] $campaign_ids Array of campaign IDs whose ad groups will be returned
  • intCreateAdGroup ( int $advertiser_id, AdGroup $ad_group )
    Create a new Ad Group.
    • The ad_group_id field of the AdGroup will be ignored.
    int $advertiser_id ID of the advertiser to create the ad group for.
    AdGroup $ad_group Data for the new ad group (see the AdGroup type)
  • int[]CreateAdGroupList ( int $advertiser_id, AdGroup[] $ad_groups )
    Create a list of ad groups.
    • The ad_group_id field of the AdGroup will be ignored.
    int $advertiser_id ID of the advertiser to create the ad groups for.
    AdGroup[] $ad_groups Array of ad groups to be created
  • boolUpdateAdGroup ( int $advertiser_id, AdGroup $ad_group )
    Update an ad group. The following fields are updatable:
    • ad_group_name
    • max_cpc
    • status
    int $advertiser_id ID of the advertiser that owns the ad group
    AdGroup $ad_group Ad Group to be created (See the AdGroup type)
  • boolUpdateAdGroupList ( int $advertiser_id, AdGroup[] $ad_groups )
    Update a list of ad groups. The following fields are updatable:
    • ad_group_name
    • max_cpc
    • status
    int $advertiser_id ID of the advertiser that owns the ad group
    AdGroup[] $ad_groups Array of ad groups to be updated
  • boolSetAdGroupPaused ( int $advertiser_id, int $ad_group_id )
    Set an ad group's status to Paused
    int $advertiser_id ID of the advertiser that owns the ad group
    int $ad_group_id ID of the ad group to be updated (Note that you can also update status manually, see the AdGroup Service)
  • boolSetAdGroupActive ( int $advertiser_id, int $ad_group_id )
    Set an ad group's status to Active
    int $advertiser_id ID of the advertiser that owns the ad group
    int $ad_group_id ID of the ad group being activated
  • StatRecord[]GetAdGroupStats ( int $advertiser_id, int[] $ad_group_ids, string $start_date, string $end_date )
    Get ad group statistics for a given time range. See StatRecord
    int $advertiser_id ID of the advertiser that owns the ad group
    int[] $ad_group_ids Array of ad group IDs to return information for
    string $start_date Date to start aggregating results
    string $end_date Date to stop aggregating results

AdGroupCategory

WSDL: AdGroupCategory.wsdl  

Provides a set of methods for retrieving, adding and updating ad group categories

  • AdGroupCategoryGetAdGroupCategory ( int $advertiser_id, int $ad_group_id, int $category_id )
    Get an ad group category
    int $advertiser_id ID of the advertiser that owns the ad group category
    int $ad_group_id ID of the ad group the category belongs to
    int $category_id ID of the category assigned to the ad group
  • AdGroupCategory[]GetAdGroupCategoryList ( int $advertiser_id, int $ad_group_id )
    Get a list of ad group categories for a supplied advertiser and ad group
    int $advertiser_id ID of the advertiser that owns the ad group category
    int $ad_group_id ID of the ad group the categories belongs to
  • AdGroupCategory[]GetActiveAdGroupCategoryList ( int $advertiser_id, int $ad_group_id )
    Get a list of active ad group categories for a supplied ad group
    int $advertiser_id ID of the advertiser that owns the ad group category
    int $ad_group_id ID of the ad group the categories belong to
  • AdGroupCategory[]GetAdGroupCategoriesByCampaign ( int $advertiser_id, int $campaign_id )
    Get a list of ad group categories for a given campaign
    int $advertiser_id ID of the advertiser that owns the ad group category
    int $campaign_id ID of the campaign the categories belong to
  • boolAddAdGroupCategory ( int $advertiser_id, AdGroupCategory $category )
    Add a category to an ad group.
    int $advertiser_id ID of the advertiser that owns the ad group to which the category is being added.
    AdGroupCategory $category The ad group category being created (see the AdGroupCategory type)
  • boolAddAdGroupCategoryList ( int $advertiser_id, AdGroupCategory[] $categories )
    Add a list of categories to an ad group
    int $advertiser_id ID of the advertiser that owns the ad group to which the categories are being added.
    AdGroupCategory[] $categories The ad group categories being created (see the AdGroupCategory type)
  • boolUpdateAdGroupCategory ( int $advertiser_id, AdGroupCategory $category )
    Update an ad group category. The following fields are updatable:
    • max_cpc
    • traffic_booster
    • use_default_bid
    • status
    int $advertiser_id ID of the advertiser that owns the ad group category
    AdGroupCategory $category The ad group category being updated (see the AdGroupCategory type)
  • boolUpdateAdGroupCategoryList ( int $advertiser_id, AdGroupCategory[] $categories )
    Update a list of ad group categories. The following fields are updatable:
    • max_cpc
    • traffic_booster
    • use_default_bid
    • status
    int $advertiser_id ID of the advertiser that owns the ad group category
    AdGroupCategory[] $categories The ad group categories being updated (see the AdGroupCategory type)
  • boolRemoveAdgroupCategory ( int $advertiser_id, int $ad_group_id, int $category_id )
    Remove a category from an ad group
    int $advertiser_id ID of the advertiser that owns the ad group category
    int $ad_group_id ID of the ad group the category belongs to
    int $category_id ID of the category being removed
  • boolSetAdGroupCategoryPaused ( int $advertiser_id, int $ad_group_id, int $category_id )
    Set an ad group category's status to paused
    int $advertiser_id ID of the advertiser that owns the ad group category
    int $ad_group_id ID of the ad group the category belongs to
    int $category_id ID of the category being paused
  • boolSetAdgroupCategoryActive ( int $advertiser_id, int $ad_group_id, int $category_id )
    Set an ad group category's status to active
    int $advertiser_id ID of the advertiser that owns the ad group category
    int $ad_group_id ID of the ad group the category belongs to
    int $category_id ID of the category being activated
  • StatRecord[]GetAdGroupCategoryStats ( int $advertiser_id, int $ad_group_id, int[] $category_ids, string $start_date, string $end_date )
    Get statistics for an ad group category. See StatRecord
    int $advertiser_id ID of the advertiser that owns the ad group category
    int $ad_group_id ID of the ad group the category belongs to
    int[] $category_ids Array of category IDs to return information for
    string $start_date Date to start aggregating results
    string $end_date Date to stop aggregating results

Advertiser

WSDL: Advertiser.wsdl  

Provides a set of methods for retrieving information about one or more advertisers

  • AdvertiserGetAdvertiser ( int $advertiser_id )
    Get an advertiser with a supplied advertiser_id
    int $advertiser_id ID of the advertiser to be returned
  • Advertiser[]GetAdvertiserList ( )
    Get a list of advertisers this account is authorized to work with.
    Only agency users will have access to multiple accounts.
  • StatRecord[]GetAdvertiserStats ( int $advertiser_id, string $start_date, string $end_date )
    Get statistics over a supplied time range for an advertiser
    int $advertiser_id ID of the advertiser to report on
    string $start_date Date to start aggregating results
    string $end_date Date to stop aggregating results
  • GeoCountry[]GetGeoCountries ( )
    Get the current list of valid countries.
  • GeoState[]GetGeoStates ( string $country_code )
    Get the current list of valid states for a given country.
    string $country_code Two-character country code
  • boolSetAdvertiserGeo ( int $advertiser_id, GeoCountry[] $countries )
    Set geo-targeting information for an advertiser. A value of 'null' or 0 removes targeting.
    int $advertiser_id The id of the advertiser.
    GeoCountry[] $countries An array of GeoCountry objects with optional GeoStates.
  • GeoCountry[]GetAdvertiserGeo ( int $advertiser_id )
    Get geo-targeting information for an advertiser.
    int $advertiser_id The id of the advertiser.

BidIndex

WSDL: BidIndex.wsdl  

Provides a set of methods for retrieving bid information

  • BidIndexGetBidIndex ( int $advertiser_id, int $ad_group_id, int $category_id, int $objective_id )
    Get a bid index by Ad Group, Category, and Objective
    int $advertiser_id ID of the advertiser that owns the ad group category bid
    int $ad_group_id ID of the ad group the bid belongs to
    int $category_id ID of the category the bid belongs to
    int $objective_id ID of the network the underlying campaign belongs to

BidPrices

WSDL: BidPrices.wsdl  

Provides a set of methods for retrieving bid information

  • GetBidPrices ( )
    Get a bid price by Category
  • GetBidPricesByCountry ( )
    Get bid price by Country Code

Campaign

WSDL: Campaign.wsdl  

Provides a set of methods for retrieving, creating and updating campaigns

  • CampaignGetCampaign ( int $advertiser_id, int $campaign_id )
    Return campaign info for a supplied campaign_id
    int $advertiser_id ID of the advertiser that owns the campaign
    int $campaign_id ID of the campaign to be returned
  • Campaign[]GetCampaignList ( int $advertiser_id )
    Get a list of campaigns for a given advertiser
    int $advertiser_id ID of the advertiser that owns the campaign
  • Campaign[]GetActiveCampaignList ( int $advertiser_id )
    Get a list of all active campaigns
    int $advertiser_id ID of the advertiser that owns the campaign
  • intCreateCampaign ( int $advertiser_id, Campaign $campaign )
    Create a campaign for a supplied advertiser
    • The campaign_id field of the Campaign will be ignored.
    int $advertiser_id ID of the advertiser to create the campaign for
    Campaign $campaign The campaign object to be created. See the Campaign type.
  • int[]CreateCampaignList ( int $advertiser_id, Campaign[] $campaigns )
    Create a list of campaigns for a supplied advertiser
    • The campaign_id field of the Campaign will be ignored.
    int $advertiser_id ID of the advertiser to create the campaigns for
    Campaign[] $campaigns Array of campaigns to be created. See the Campaign type.
  • boolUpdateCampaign ( int $advertiser_id, Campaign $campaign )
    Update a campaign for a supplied advertiser. The following fields are updatable:
    • campaign_name
    • daily_budget
    • lifetime_budget
    • start_date
    • end_date
    • status
    int $advertiser_id ID of the advertiser that owns the campaign
    Campaign $campaign Campaign object to be updated
  • boolUpdateCampaignList ( int $advertiser_id, Campaign[] $campaigns )
    Update a list of campaigns for a supplied advertiser. The following fields are updatable:
    • campaign_name
    • daily_budget
    • lifetime_budget
    • start_date
    • end_date
    • status
    int $advertiser_id ID of the advertiser that owns the campaign
    Campaign[] $campaigns Array of campaign objects to be updated
  • boolSetCampaignPaused ( int $advertiser_id, int $campaign_id )
    Set a campaign's status to Paused
    int $advertiser_id ID of the advertiser that owns the campaign
    int $campaign_id ID of the campaign being paused
  • boolSetCampaignActive ( int $advertiser_id, int $campaign_id )
    Set a campaign's status to Active
    int $advertiser_id ID of the advertiser that owns the campaign
    int $campaign_id ID of the campaign being activated
  • StatRecord[]GetCampaignStats ( int $advertiser_id, int[] $campaign_ids, string $start_date, string $end_date )
    Get statistics for a supplied list of campaigns in a given date range. See StatRecord
    int $advertiser_id ID of the advertiser that owns the campaign
    int[] $campaign_ids Array of campaign IDs to return information for
    string $start_date Date to start aggregating results
    string $end_date Date to stop aggregating results
  • CampaignBidCost[]GetCampaignBidCostList ( int $advertiser_id, int[] $campaign_ids, string $start_date, string $end_date )
    Get the statisitcs for clicks and costs for a list of campaign ids.
    int $advertiser_id ID of the advertiser that owns the campaign
    int[] $campaign_ids Array of campaign IDs to return information for
    string $start_date Date to start aggregating results
    string $end_date Data to stop aggregating results
  • GeoCountry[]GetGeoCountries ( )
    Get the current list of valid countries.
  • GeoState[]GetGeoStates ( string $country_code )
    Get the current list of valid states for a given country.
    string $country_code Two-character country code
  • boolSetCampaignGeo ( int $advertiser_id, int $campaign_id, GeoCountry[] $countries )
    Set geo-targeting information for a campaign. A value of 'null' or 0 removes targeting.
    int $advertiser_id The id of the advertiser that owns the campaign.
    int $campaign_id The id of the campaign for which geo-targeting will be set.
    GeoCountry[] $countries An array of GeoCountry objects with optional GeoStates.
  • GeoCountry[]GetCampaignGeo ( int $advertiser_id, int $campaign_id )
    Get geo-targeting information for a campaign.
    int $advertiser_id The id of the advertiser that owns the campaign.
    int $campaign_id The id of the campaign for which geo-targeting will be set.
  • boolEnableCampaignDayParting ( int $advertiser_id, int $campaign_id )
    Enable day parting for a campaign.
    int $advertiser_id The ID of the advertiser that owns the campaign.
    int $campaign_id The ID of the campaign on which to enable day parting.
  • boolDisableCampaignDayParting ( int $advertiser_id, int $campaign_id )
    Disable day parting for a campaign.
    int $advertiser_id The ID of the advertiser that owns the campaign.
    int $campaign_id The ID of the campaign on which to disable day parting.
  • DayPartingGetCampaignDayParting ( int $advertiser_id, int $campaign_id )
    Get day parting information for a campaign.
    int $advertiser_id The ID of the advertiser that owns the campaign.
    int $campaign_id The ID of the campaign on which to get day parting.
  • DayParting[]GetCampaignListDayParting ( int $advertiser_id, int[] $campaign_ids )
    Get day parting information for a list of campaigns.
    int $advertiser_id The ID of the advertiser that owns the campaigns.
    int[] $campaign_ids An array of IDs for the campaigns on which to get day parting.
  • boolSetCampaignDayParting ( int $advertiser_id, DayParting $day_parting )
    Set day parting information for a campaign.
    int $advertiser_id The ID of the advertiser that owns the campaign.
    DayParting $day_parting The day parting information to set.
  • boolSetCampaignListDayParting ( int $advertiser_id, DayParting[] $day_partings )
    Set day parting information for a list of campaigns.
    int $advertiser_id The ID of the advertiser that owns the campaigns.
    DayParting[] $day_partings An array of day parting informations to set.

Category

WSDL: Category.wsdl  

Provides a set of methods for retrieving category information

  • Category[]GetCategoryList ( )
    Returns a list of tier 3 categories. (Only tier 3 categories can be assigned to ad groups. For advice, please contact your account manager.)

Listing

WSDL: Listing.wsdl  

Provides a set of methods for retrieving, creating and updating listings

  • ListingGetListing ( int $advertiser_id, int $listing_id )
    Get a listing via a supplied listing id
    int $advertiser_id ID of the advertiser of whom the listing belongs to
    int $listing_id ID of the listing to be returned
  • Listing[]GetListingList ( int $advertiser_id, int[] $listing_ids )
    Get a list of listings by their listing ids
    int $advertiser_id ID of the advertiser of whom the listings belong to
    int[] $listing_ids Array of listing IDs to be returned
  • Listing[]GetListingsByCampaign ( int $advertiser_id, int[] $campaign_ids )
    Get a list of listings for a given set of campaign ids
    int $advertiser_id ID of the advertiser of whom the listings belong to
    int[] $campaign_ids Array of campaign IDs whose listings will be returned
  • Listing[]GetActiveListingsByCampaign ( int $advertiser_id, int[] $campaign_ids )
    Get a list of active listings for a given set of campaign ids
    int $advertiser_id ID of the advertiser of whom the listings belong to
    int[] $campaign_ids Array of campaign IDs whose listings will be returned
  • Listing[]GetListingsByAdGroup ( int $advertiser_id, int[] $ad_group_ids )
    Get a list of listings for a given set of ad group ids
    int $advertiser_id ID of the advertiser of whom the listings belong to
    int[] $ad_group_ids Array of ad group IDs whose listings will be returned
  • Listing[]GetActiveListingsByAdGroup ( int $advertiser_id, int[] $ad_group_ids )
    Get a list of active listings for a given set of ad group ids
    int $advertiser_id ID of the advertiser of whom the listings belong to
    int[] $ad_group_ids Array of ad group IDs whose listings will be returned
  • intCreateListing ( int $advertiser_id, Listing $listing )
    Create a listing.
    • The listing_id, create_date, rejected_reason and display_status fields of the Listing will be ignored.
    int $advertiser_id ID of the advertiser to create the listing for
    Listing $listing The Listing to be created
  • int[]CreateListingList ( int $advertiser_id, Listing[] $listings )
    Create a set of listings.
    • The listing_id, create_date, rejected_reason and display_status fields of the Listing will be ignored.
    int $advertiser_id ID of the advertiser to create the listings for
    Listing[] $listings Array of Listings to be created
  • boolUpdateListing ( int $advertiser_id, Listing $listing )
    Update a listing's information. The following fields are updatable:
    • title
    • description
    • url
    • display_url
    • status
    int $advertiser_id ID of the advertiser who owns the listing
    Listing $listing The Listing to be updated
  • boolUpdateListingList ( int $advertiser_id, Listing[] $listings )
    Update a set of listings. The following fields are updatable:
    • title
    • description
    • url
    • display_url
    • status
    int $advertiser_id ID of the advertiser who owns the listings
    Listing[] $listings Array of listings to be updated
  • StatRecord[]GetListingStats ( int $advertiser_id, int[] $listing_ids, string $start_date, string $end_date )
    Get statistical information about a set of listings. See StatRecord
    int $advertiser_id ID of the advertiser that owns the listings
    int[] $listing_ids Array of listing IDs to be reported on
    string $start_date Date to begin aggregating results
    string $end_date Date to stop aggregating results

Network

WSDL: Network.wsdl  

Provides a set of methods for retrieving network information

  • Network[]GetNetworkList ( )
    Return a list of all networks
  • NetworkGetNetworkByName ( string $network_name )
    Returns network data matching a supplied name
    string $network_name
  • NetworkGetNetworkById ( int $network_id )
    Returns network data matching a supplied ID
    int $network_id
  • floatGetNetworkCategoryMinBid ( int $network_id, int $category_id )
    Returns the minimum bid for the given category in a network.
    int $network_id
    int $category_id

Transaction

WSDL: Transaction.wsdl  

Provides a set of methods for retrieving transaction info and history

  • TransactionGetLastTransaction ( int $advertiser_id )
    Returns the last transaction placed for a supplied advertiser
    int $advertiser_id ID of the advertiser the transaction belongs to
  • Transaction[]GetTransactionHistory ( int $advertiser_id, string $start_date, string $end_date )
    Get a history of all transactions for a given date range
    int $advertiser_id ID of the advertiser that the transactions belong to
    string $start_date Date to begin looking for transactions
    string $end_date Date to stop looking for transaction

Complex Types

int ad_group_id The ad group's ID
int campaign_id The campaign's ID
string ad_group_name The ad group's name
float max_cpc Your Max CPC for this ad group
string status The current status of this ad group. Valid statuses are ACTIVE, INACTIVE and DELETED
int ad_group_id The ad group ID this ad group category belongs to
int category_id The category ID assigned to this ad group
string category_name The name of the category assigned to this ad group
string destination_url Use this field to override the destination url for the associated listing.
float max_cpc The max CPC for this ad group category. Subject to the restriction of this category's minimum bid.
string status The advertiser defined status of this ad group category
string display_status The BidSystem defined status of this ad group category. Valid statuses are ACTIVE, INACTIVE and DELETED
bool use_default_bid Flags whether or not this ad group category should respect its ad group's max CPC
float traffic_booster Traffic booster setting for this ad group category. Possible values are 0 (Off) .8 (80%) .9 (90%) 1 (100%)
bool is_cpa Flags whether or not this ad group category is a CPA
float target_cpa The target cpa for this ad group category. Subject to the restriction of this category's minimum bid.
float ecvr The estimated conversion rate for the ad group category. Subject to the restriction of this category's minimum bid.
int advertiser_id The advertiser's ID
string account_name The advertiser's account name
string status The advertiser's current account status
float balance The advertiser's current balance
bool auto_pay Flags whether or not auto pay is turned on
float auto_pay_amount If auto pay is enabled, this is the amount to be deducted.
string create_date The date the advertiser's account was created
string email The advertiser's account email
string login_id The advertiser's login ID
bool confirmed Flags whether or not this advertiser has been confirmed
int ad_group_id The Ad Group ID of the requested bid index.
int category_id The Category ID of the requested bid index.
int objective_id The Objective ID of the requested bid index.
float bid The bid of the requested bid index.
bool default_bid True if the bid is a default bid at the Ad Group level, false if the bid is an override bid at the Category level.
float bid_index The bid index value itself.
float bidprice The bidprice of the category
int rank
int campaign_id The ID of this campaign
string campaign_name The name of this campaign
int advertiser_id The ID of the advertiser that owns this campaign
string status The current status of this campaign. Valid statuses are ACTIVE, INACTIVE and DELETED
string create_date The date this campaign was created
string start_date The date this campaign is due to start
string end_date
int network_id The network ID for this campaign
string network_name The name of the network that this campaign is in
float daily_budget The daily budget for this campaign. (0 for unlimited)
float lifetime_budget The lifetime budget for this campaign. (0 for unlimited)
int category_id This category's ID
string category_name The name of this category
string category_full_name The category's fully qualified name
int category_level The level or tier this category belongs to (Only tier 3 categories can be assigned to ad groups)
int listing_id This listing's ID
int campaign_id This listing's Campaign ID
int ad_group_id This listing's Ad Group ID
string status The current advertiser defined status of this listing. Valid statuses are ACTIVE, INACTIVE and DELETED
string display_status The current BidSystem defined status of this listing
string title The listing's displayed title
string description The listing's displayed description. No newlines.
string url The listing's URL. This is where people will go when clicking on your ads.
string display_url The listing's display URL. This is what is displayed with your ad. Optional.
string create_date The date the listing was created
string rejected_reason The reason, if any, this listing was rejected by our system.
int override_cppc This determines if the cppc should be overriden or not. Optional.
float ppc The ppc value. Optional.
string API_KEY The API Key that was assigned to you
string PASSWORD The password that was assigned to you
int network_id The ID of the network
string network_name The name of the network
int id The ID of the entity being reported on
int clicks The number of clicks for the specified date range
int conversions The number of conversions for the specified date range
float cost The total cost accrued for the specified date range
float cpa The Cost/Conversions for this time period.
float cpc The Cost per Click for this time period
string last_update The last time advertiser reports were updated
int transaction_id The ID for this transaction. This is not the invoice number.
int advertiser_id The advertiser that owns this transaction
string transaction_date The date this transaction occurred.
string type The type of transaction (CREDIT, PAYMENT, INVOICE, TRANSFER, REFUND)
float amount The amount processed, in USD
string message The message or additional information associated with this transaction