API Evangelist conversational phrasing for Google Ads Customers API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Google Ads Customers API
  version: 1.0.0
extends: openapi/google-ads-customers-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-02'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 33
- target: $.paths['/v18/customers/{customerId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a Google Ads account's details
      effect: read
      questions:
      - What details can I pull back about a single Google Ads account through the v18 API?
      - Can I tell whether an account is a manager account or a regular client account?
      instructions:
      - text: Get the full account details for Google Ads customer {customer} using the v18 endpoint.
        slots:
          customer: path.customerId
      - text: Show me the v18 account record for {customer}, including whether it is a manager account.
        slots:
          customer: path.customerId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v18/customers:listAccessibleCustomers'].get
  update:
    x-apievangelist-phrasing:
      intent: List accounts my login can access (v18)
      effect: read
      questions:
      - Which Google Ads accounts can my OAuth login reach directly on the v18 API?
      - Is there a way to find my customer IDs without already knowing one?
      instructions:
      - text: Using developer token {devtoken}, list every account my credentials can access on v18.
        slots:
          devtoken: header.developer-token
      - text: Find the v18 customer resource names I can reach with developer token {devtoken}.
        slots:
          devtoken: header.developer-token
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v25/customers/{customersId}:generateShareablePreviews'].post
  update:
    x-apievangelist-phrasing:
      intent: Generate shareable ad previews
      effect: read
      questions:
      - Can I produce a preview link of my ads to share with a client who has no account access?
      - What does a shareable preview for an asset group look like before it goes live?
      instructions:
      - text: Generate shareable previews for account {customer}.
        slots:
          customer: path.customersId
      - text: Create a shareable preview link in account {customer} using preview request {operation}.
        slots:
          customer: path.customersId
          operation: requestBody.operation
      method: generated
      generated: '2026-10-02'
- target: $.paths['/v25/customers:listAccessibleCustomers'].get
  update:
    x-apievangelist-phrasing:
      intent: List accounts my login can access (v25)
      effect: read
      questions:
      - Which customer accounts does my authenticated user reach directly on the current v25 API?
      - What comes back from the v25 accessible-customers call when I have several accounts?
      instructions:
      - text: List the customer resource names my current credentials can access on v25.
      - text: Show all accounts directly accessible to the user I authenticated as, via v25.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v25/customers/{customersId}:generateKeywordHistoricalMetrics'].post
  update:
    x-apievangelist-phrasing:
      intent: Get historical metrics for keywords
      effect: read
      questions:
      - How many monthly searches did a set of keywords get historically?
      - Can I see past search volume and competition for keywords in one language and location?
      - Does the historical keyword metrics call let me exclude adult keywords?
      instructions:
      - text: Get historical search metrics for keywords {keywords} in account {customer}.
        slots:
          keywords: requestBody.keywords
          customer: path.customersId
      - text: Pull historical volume for {keywords} in language {language} for account {customer}.
        slots:
          keywords: requestBody.keywords
          language: requestBody.language
          customer: path.customersId
      method: generated
      generated: '2026-10-02'
- target: $.paths['/v25/customers/{customersId}:suggestKeywordThemes'].post
  update:
    x-apievangelist-phrasing:
      intent: Suggest keyword themes for a Smart campaign
      effect: read
      questions:
      - What keyword themes would suit my business for a Smart campaign?
      - Can I get keyword theme suggestions based on my business details?
      instructions:
      - text: Suggest keyword themes to advertise on for account {customer}.
        slots:
          customer: path.customersId
      - text: Suggest keyword themes for account {customer} from business info {info}.
        slots:
          customer: path.customersId
          info: requestBody.suggestionInfo
      method: generated
      generated: '2026-10-02'
- target: $.paths['/v25/customers/{customersId}:generateAudienceDefinition'].post
  update:
    x-apievangelist-phrasing:
      intent: Turn a text description into an audience
      effect: read
      questions:
      - Can I describe my ideal audience in plain words and get targetable attributes back?
      - Which audience attributes does generative AI suggest for a written audience description?
      instructions:
      - text: Generate audience attributes for account {customer} from the description {description}.
        slots:
          customer: path.customersId
          description: requestBody.audienceDescription
      - text: Use AI to build an audience definition in account {customer} for {description}.
        slots:
          customer: path.customersId
          description: requestBody.audienceDescription
      method: generated
      generated: '2026-10-02'
- target: $.paths['/v25/customers/{customersId}:generateTrendingInsights'].post
  update:
    x-apievangelist-phrasing:
      intent: Get trending YouTube content insights
      effect: read
      questions:
      - What content is trending on YouTube for my audience in a given country?
      - Can I see trending YouTube topics filtered to specific search topics?
      instructions:
      - text: Show trending YouTube content insights for account {customer} in country {country}.
        slots:
          customer: path.customersId
          country: requestBody.countryLocation
      - text: Get trending insights for account {customer} around topics {topics}.
        slots:
          customer: path.customersId
          topics: requestBody.searchTopics
      method: generated
      generated: '2026-10-02'
- target: $.paths['/v25/customers/{customersId}:generateAudienceOverlapInsights'].post
  update:
    x-apievangelist-phrasing:
      intent: Estimate audience overlap on YouTube
      effect: read
      questions:
      - How much does one audience attribute's YouTube reach overlap with others?
      - Which attributes share the most potential reach with my primary audience?
      instructions:
      - text: Estimate YouTube reach overlap with attribute {primary} for account {customer} in {country}.
        slots:
          primary: requestBody.primaryAttribute
          customer: path.customersId
          country: requestBody.countryLocation
      - text: Compare audience overlap for primary attribute {primary} in account {customer}.
        slots:
          primary: requestBody.primaryAttribute
          customer: path.customersId
      method: generated
      generated: '2026-10-02'
- target: $.paths['/v25/customers/{customersId}:suggestSmartCampaignBudgetOptions'].post
  update:
    x-apievangelist-phrasing:
      intent: Suggest budgets for a Smart campaign
      effect: read
      questions:
      - What daily budget options are recommended for a Smart campaign?
      - Can I get budget suggestions for an existing Smart campaign rather than a new one?
      instructions:
      - text: Suggest Smart campaign budget options for account {customer}.
        slots:
          customer: path.customersId
      - text: Get budget option suggestions for Smart campaign {campaign} in account {customer}.
        slots:
          campaign: requestBody.campaign
          customer: path.customersId
      method: generated
      generated: '2026-10-02'
- target: $.paths['/v25/customers/{customersId}:generateSuggestedTargetingInsights'].post
  update:
    x-apievangelist-phrasing:
      intent: Suggest audiences relevant to my audience
      effect: read
      questions:
      - Which targetable audiences are relevant to the audience I care about?
      - Can I get targeting suggestions from a free-text audience description?
      instructions:
      - text: Suggest targeting insights for account {customer} based on audience {audience}.
        slots:
          customer: path.customersId
          audience: requestBody.audienceDefinition
      - text: Find targetable audiences in account {customer} matching the description {description}.
        slots:
          customer: path.customersId
          description: requestBody.audienceDescription
      method: generated
      generated: '2026-10-02'
- target: $.paths['/v25/customers/{customersId}:generateKeywordForecastMetrics'].post
  update:
    x-apievangelist-phrasing:
      intent: Forecast clicks and cost for a keyword plan
      effect: read
      questions:
      - What impressions, clicks and cost should I expect from a planned campaign's keywords?
      - Can I forecast keyword performance over a specific future period and currency?
      instructions:
      - text: Forecast keyword metrics for campaign {campaign} in account {customer}.
        slots:
          campaign: requestBody.campaign
          customer: path.customersId
      - text: Forecast impressions and cost for {campaign} over period {period} in account {customer}.
        slots:
          campaign: requestBody.campaign
          period: requestBody.forecastPeriod
          customer: path.customersId
      method: generated
      generated: '2026-10-02'
- target: $.paths['/v25/customers/{customersId}:generateCreatorInsights'].post
  update:
    x-apievangelist-phrasing:
      intent: Get insights on YouTube creators
      effect: read
      questions:
      - Which YouTube creators and channels reach audiences in my target countries?
      - Can I look up insights for specific YouTube channels I already have in mind?
      instructions:
      - text: Get creator insights for channels {channels} in account {customer}.
        slots:
          channels: requestBody.searchChannels
          customer: path.customersId
      - text: Find YouTube creators on topics {topics} in countries {countries} for account {customer}.
        slots:
          topics: requestBody.searchTopics
          countries: requestBody.countryLocations
          customer: path.customersId
      method: generated
      generated: '2026-10-02'
- target: $.paths['/v25/customers/{customersId}:uploadClickConversions'].post
  update:
    x-apievangelist-phrasing:
      intent: Upload offline click conversions
      effect: write
      questions:
      - How do I send offline sales tied to ad clicks back to my account?
      - Can a click conversion upload accept some rows even when others fail?
      - Is there a validate-only mode for testing click conversion uploads?
      instructions:
      - text: Upload click conversions {conversions} to account {customer}.
        slots:
          conversions: requestBody.conversions
          customer: path.customersId
      - text: Validate click conversions {conversions} for account {customer} without saving them.
        slots:
          conversions: requestBody.conversions
          customer: path.customersId
      method: generated
      generated: '2026-10-02'
- target: $.paths['/v25/customers/{customersId}:suggestTravelAssets'].post
  update:
    x-apievangelist-phrasing:
      intent: Suggest travel assets for hotels
      effect: read
      questions:
      - Can I get ad asset suggestions for a hotel property from its place ID?
      - Which travel assets are suggested for my hotels, and is every asset type guaranteed?
      instructions:
      - text: Suggest travel assets for place IDs {places} in account {customer}.
        slots:
          places: requestBody.placeIds
          customer: path.customersId
      - text: Get hotel asset suggestions in language {language} for {places} in account {customer}.
        slots:
          language: requestBody.languageOption
          places: requestBody.placeIds
          customer: path.customersId
      method: generated
      generated: '2026-10-02'
- target: $.paths['/v25/customers/{customersId}:uploadUserData'].post
  update:
    x-apievangelist-phrasing:
      intent: Upload user data to a Customer Match list
      effect: write
      questions:
      - What's the direct way to add hashed contact data to a Customer Match list?
      - Can I push user data straight into a list without creating an offline job first?
      instructions:
      - text: Upload user data operations {operations} to account {customer}.
        slots:
          operations: requestBody.operations
          customer: path.customersId
      - text: Add these customers {operations} to the Customer Match list {metadata} in account {customer}.
        slots:
          operations: requestBody.operations
          metadata: requestBody.customerMatchUserListMetadata
          customer: path.customersId
      method: generated
      generated: '2026-10-02'
- target: $.paths['/v25/customers/{customersId}:uploadConversionAdjustments'].post
  update:
    x-apievangelist-phrasing:
      intent: Adjust or retract reported conversions
      effect: write
      questions:
      - Can I restate the value of a conversion that was already reported?
      - How do I retract conversions for orders that were later refunded?
      instructions:
      - text: Upload conversion adjustments {adjustments} to account {customer}.
        slots:
          adjustments: requestBody.conversionAdjustments
          customer: path.customersId
      - text: Retract or restate conversions {adjustments} in account {customer}, allowing partial failure.
        slots:
          adjustments: requestBody.conversionAdjustments
          customer: path.customersId
      method: generated
      generated: '2026-10-02'
- target: $.paths['/v25/customers/{customersId}:removeCampaignAutomaticallyCreatedAsset'].post
  update:
    x-apievangelist-phrasing:
      intent: Remove auto-created assets from a campaign
      effect: destructive
      questions:
      - Can I get rid of assets Google created automatically at the campaign level?
      - What happens to campaign assets I didn't write myself if I remove them?
      instructions:
      - text: Remove the automatically created campaign assets {operations} in account {customer}.
        slots:
          operations: requestBody.operations
          customer: path.customersId
      - text: Strip auto-generated assets from campaigns in account {customer}.
        slots:
          customer: path.customersId
      method: generated
      generated: '2026-10-02'
- target: $.paths['/v25/customers/{customersId}:generateAudienceCompositionInsights'].post
  update:
    x-apievangelist-phrasing:
      intent: Compare an audience's makeup to a baseline
      effect: read
      questions:
      - What attributes over-index in my audience compared with a baseline audience?
      - Can I see audience composition for a particular data month?
      instructions:
      - text: Generate audience composition insights for audience {audience} in account {customer}.
        slots:
          audience: requestBody.audience
          customer: path.customersId
      - text: Compare audience {audience} against baseline {baseline} for account {customer}.
        slots:
          audience: requestBody.audience
          baseline: requestBody.baselineAudience
          customer: path.customersId
      method: generated
      generated: '2026-10-02'
- target: $.paths['/v25/customers/{customersId}:suggestSmartCampaignAd'].post
  update:
    x-apievangelist-phrasing:
      intent: Suggest a Smart campaign ad
      effect: read
      questions:
      - Can Google write a Smart campaign ad for me from my business details?
      - What ad text is suggested for a Smart campaign based on targeting and business info?
      instructions:
      - text: Suggest a Smart campaign ad for account {customer}.
        slots:
          customer: path.customersId
      - text: Draft a Smart campaign ad in account {customer} using business info {info}.
        slots:
          customer: path.customersId
          info: requestBody.suggestionInfo
      method: generated
      generated: '2026-10-02'
- target: $.paths['/v25/customers/{customersId}:startIdentityVerification'].post
  update:
    x-apievangelist-phrasing:
      intent: Start advertiser identity verification
      effect: write
      questions:
      - How do I kick off advertiser identity verification for my account?
      - Which verification program can I start through the API?
      instructions:
      - text: Start identity verification for account {customer}.
        slots:
          customer: path.customersId
      - text: Begin verification program {program} for account {customer}.
        slots:
          program: requestBody.verificationProgram
          customer: path.customersId
      method: generated
      generated: '2026-10-02'
- target: $.paths['/v25/customers/{customersId}:generateReachForecast'].post
  update:
    x-apievangelist-phrasing:
      intent: Forecast reach for a YouTube media plan
      effect: read
      questions:
      - How many people could a planned YouTube product mix reach for my budget?
      - Can I forecast reach with a frequency cap and a set campaign duration?
      instructions:
      - text: Generate a reach forecast for account {customer} with planned products {products}.
        slots:
          customer: path.customersId
          products: requestBody.plannedProducts
      - text: Forecast reach for {products} over {duration} in currency {currency} for account {customer}.
        slots:
          products: requestBody.plannedProducts
          duration: requestBody.campaignDuration
          currency: requestBody.currencyCode
          customer: path.customersId
      method: generated
      generated: '2026-10-02'
- target: $.paths['/v25/customers/{customersId}/getIdentityVerification'].get
  update:
    x-apievangelist-phrasing:
      intent: Check identity verification status
      effect: read
      questions:
      - Has my account finished advertiser identity verification yet?
      - Where can I see the current verification status and deadlines for an account?
      instructions:
      - text: Get the identity verification status for account {customer}.
        slots:
          customer: path.customersId
      - text: Check whether account {customer} still needs to verify its identity.
        slots:
          customer: path.customersId
      method: generated
      generated: '2026-10-02'
- target: $.paths['/v25/customers/{customersId}:suggestBrands'].post
  update:
    x-apievangelist-phrasing:
      intent: Look up brands by name prefix
      effect: read
      questions:
      - Can I search for a brand by typing the first few letters of its name?
      - Which brands match a prefix, excluding ones I've already selected?
      instructions:
      - text: Suggest brands starting with {prefix} for account {customer}.
        slots:
          prefix: requestBody.brandPrefix
          customer: path.customersId
      - text: Find matching brands for {prefix} in account {customer}, skipping {selected}.
        slots:
          prefix: requestBody.brandPrefix
          customer: path.customersId
          selected: requestBody.selectedBrands
      method: generated
      generated: '2026-10-02'
- target: $.paths['/v25/customers/{customersId}:mutate'].post
  update:
    x-apievangelist-phrasing:
      intent: Update an account's settings
      effect: write
      questions:
      - Can I change settings on an existing customer account, like its tracking template?
      - Is there a way to check an account update is valid without applying it?
      instructions:
      - text: Update account {customer} with change {operation}.
        slots:
          customer: path.customersId
          operation: requestBody.operation
      - text: Validate the account settings change {operation} on {customer} without applying it.
        slots:
          operation: requestBody.operation
          customer: path.customersId
      method: generated
      generated: '2026-10-02'
- target: $.paths['/v25/customers/{customersId}:generateKeywordIdeas'].post
  update:
    x-apievangelist-phrasing:
      intent: Generate new keyword ideas
      effect: read
      questions:
      - What new keywords should I target based on a seed keyword or my website URL?
      - Can I get keyword ideas for a specific language and set of locations?
      - Is it possible to page through a long list of keyword ideas?
      instructions:
      - text: Generate keyword ideas for account {customer} from seed {seed}.
        slots:
          customer: path.customersId
          seed: requestBody.keywordSeed
      - text: Suggest keywords from the page {url} for account {customer}.
        slots:
          url: requestBody.urlSeed
          customer: path.customersId
      - text: Find keyword ideas for site {site} in account {customer}.
        slots:
          site: requestBody.siteSeed
          customer: path.customersId
      method: generated
      generated: '2026-10-02'
- target: $.paths['/v25/customers/{customersId}:generateInsightsFinderReport'].post
  update:
    x-apievangelist-phrasing:
      intent: Save an Insights Finder report
      effect: write
      questions:
      - Can I create a saved report to open later in the Insights Finder tool?
      - How can I share an audience comparison as an Insights Finder report?
      instructions:
      - text: Create an Insights Finder report for audience {audience} in account {customer}.
        slots:
          audience: requestBody.specificAudience
          customer: path.customersId
      - text: Save an Insights Finder report comparing {audience} to {baseline} for account {customer}.
        slots:
          audience: requestBody.specificAudience
          baseline: requestBody.baselineAudience
          customer: path.customersId
      method: generated
      generated: '2026-10-02'
- target: $.paths['/v25/customers/{customersId}:uploadCallConversions'].post
  update:
    x-apievangelist-phrasing:
      intent: Upload phone call conversions
      effect: write
      questions:
      - Can I report conversions that happened over the phone from my ads?
      - What happens if some rows in a call conversion upload are invalid?
      instructions:
      - text: Upload call conversions {conversions} to account {customer}.
        slots:
          conversions: requestBody.conversions
          customer: path.customersId
      - text: Validate call conversions {conversions} for account {customer} without recording them.
        slots:
          conversions: requestBody.conversions
          customer: path.customersId
      method: generated
      generated: '2026-10-02'
- target: $.paths['/v25/customers/{customersId}:generateAdGroupThemes'].post
  update:
    x-apievangelist-phrasing:
      intent: Suggest ad groups for a set of keywords
      effect: read
      questions:
      - Which of my ad groups should each new keyword go into?
      - Can I get suggested match types and text tweaks when grouping keywords?
      instructions:
      - text: Suggest ad group themes for keywords {keywords} in account {customer}.
        slots:
          keywords: requestBody.keywords
          customer: path.customersId
      - text: Match keywords {keywords} to ad groups {adgroups} in account {customer}.
        slots:
          keywords: requestBody.keywords
          adgroups: requestBody.adGroups
          customer: path.customersId
      method: generated
      generated: '2026-10-02'
- target: $.paths['/v25/customers/{customersId}:createCustomerClient'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a client account under a manager
      effect: write
      questions:
      - How do I open a new client account under my manager account?
      - Can I invite a user by email with an access role when creating a client account?
      instructions:
      - text: Create a new client account {client} under manager {customer}.
        slots:
          client: requestBody.customerClient
          customer: path.customersId
      - text: Create client {client} under manager {customer} and invite {email} as {role}.
        slots:
          client: requestBody.customerClient
          customer: path.customersId
          email: requestBody.emailAddress
          role: requestBody.accessRole
      method: generated
      generated: '2026-10-02'
- target: $.paths['/v25/customers/{customersId}:generateBenchmarksMetrics'].post
  update:
    x-apievangelist-phrasing:
      intent: Benchmark YouTube ad metrics vs industry
      effect: read
      questions:
      - How do my YouTube ad metrics compare with industry benchmarks?
      - Can I benchmark against a specific location and date range?
      instructions:
      - text: Benchmark YouTube ad metrics for account {customer} over {range}.
        slots:
          customer: path.customersId
          range: requestBody.dateRange
      - text: Compare account {customer} to benchmarks source {source} in location {location}.
        slots:
          customer: path.customersId
          source: requestBody.benchmarksSource
          location: requestBody.location
      method: generated
      generated: '2026-10-02'
- target: $.paths['/v25/customers/{customersId}:searchAudienceInsightsAttributes'].post
  update:
    x-apievangelist-phrasing:
      intent: Search audience attributes for insights
      effect: read
      questions:
      - Which audience attributes can I use when generating audience insights?
      - Can I search attributes by free text and limit them to certain countries?
      instructions:
      - text: Search audience insight attributes matching {text} in account {customer}.
        slots:
          text: requestBody.queryText
          customer: path.customersId
      - text: Find audience attributes for {text} across dimensions {dimensions} in account {customer}.
        slots:
          text: requestBody.queryText
          dimensions: requestBody.dimensions
          customer: path.customersId
      method: generated
      generated: '2026-10-02'
- target: $.paths['/v25/customers/{customersId}:generateTargetingSuggestionMetrics'].post
  update:
    x-apievangelist-phrasing:
      intent: Estimate reach for targetable audiences
      effect: read
      questions:
      - How many men aged 18+ interested in camping can I reach on YouTube?
      - What potential reach do my candidate audiences have?
      instructions:
      - text: Estimate potential reach for audiences {audiences} in account {customer}.
        slots:
          audiences: requestBody.audiences
          customer: path.customersId
      - text: Get targeting suggestion metrics for account {customer}.
        slots:
          customer: path.customersId
      method: generated
      generated: '2026-10-02'