Skip to main content

Harvest Search Terms

POST 

/api/advertising/search-terms/harvest

Harvests converting search terms into keywords. For each item SKU.io proposes an exact-match keyword in the destination ad group, and (unless negate_in_source is false) an exact negative keyword in the source campaign so the term stops competing with itself. The source negative depends on its keyword (the negative line's depends_on_change_id is the keyword line's id): it applies only after the keyword was created, fails if the keyword fails, and cannot be approved without it. The bid defaults to the term's 30-day CPC in the source campaign x 1.1, else 0.75.

Required scope: advertising:write

Grant this scope to your token under Settings → Developer → Personal Access Tokens.

The result is a change set that must be approved before anything reaches the ad platform (or a simulated set with dry_run: true).

Requires the advertising.manage permission and the Advertising Manager feature.

Body fields:

  • ad_account_id (required, existing ad account ID)
  • dry_run (optional, boolean, default false): true creates a simulated change set only
  • items (required, 1-500 rows):
    • items.*.ad_campaign_id (required, integer): the campaign the term appeared in; must be a live campaign of the account
    • items.*.ad_group_id (optional, integer)
    • items.*.search_term (required, string, max 500)
    • items.*.destination_ad_group_id (integer)
    • items.*.bid (optional, > 0)
    • items.*.negate_in_source (optional, boolean)
    • items.*.match_type (optional, exact or phrase)

For harvest, items.*.destination_ad_group_id is required and must belong to the account. items.*.match_type is ignored (harvested keywords are always exact).

Returns 201 with the change set and its lines.

Request​

Responses​

Created

Response Headers
    Content-Type