# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Impact Ads API
  version: 1.0.0
extends: openapi/impact-ads-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-26'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 9
- target: $.paths['/Advertisers/{AccountSID}/Ads'].get
  update:
    x-apievangelist-phrasing:
      intent: List a brand's ads
      effect: read
      questions:
      - Which ads has my brand created on impact.com, newest first?
      - Can I filter my brand's ads by campaign or ad type?
      - Which of the ads I created were updated in a given date range?
      instructions:
      - text: List all ads I've created in advertiser account {sid}.
        slots:
          sid: path.AccountSID
      - text: In account {sid}, show my brand ads of type {type} for campaign {campaign}.
        slots:
          sid: path.AccountSID
          type: query.Type
          campaign: query.CampaignId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/Advertisers/{AccountSID}/Ads'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a banner, coupon or text link ad
      effect: write
      questions:
      - How do I create a new banner ad for my program?
      - Can I upload a creative file when making a coupon or text link ad?
      instructions:
      - text: Create a {type} ad named {name} in campaign {campaign} for account {sid} in {lang}.
        slots:
          sid: path.AccountSID
          type: requestBody.AdType
          name: requestBody.Name
          campaign: requestBody.CampaignId
          lang: requestBody.Language
      - text: Make a new text link ad {name} pointing at {landing}, type {type}, campaign {campaign}, language {lang}.
        slots:
          name: requestBody.Name
          landing: requestBody.LandingPage
          type: requestBody.AdType
          campaign: requestBody.CampaignId
          lang: requestBody.Language
      method: generated
      generated: '2026-09-26'
- target: $.paths['/Advertisers/{AccountSID}/Ads/{AdId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a brand ad's details
      effect: read
      questions:
      - What are the settings on one of the ads my brand created?
      - Can I look up an ad I own by its impact.com Ad ID?
      instructions:
      - text: Get details of my brand ad {ad} in account {sid}.
        slots:
          sid: path.AccountSID
          ad: path.AdId
      - text: Show the configuration of advertiser ad {ad}.
        slots:
          ad: path.AdId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/Advertisers/{AccountSID}/Ads/{AdId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update an existing ad
      effect: write
      questions:
      - How do I swap the creative on an ad I already published?
      - Can I change an existing ad's landing page or labels?
      instructions:
      - text: 'Update ad {ad} in account {sid}: name {name}, type {type}, campaign {campaign}, language {lang}.'
        slots:
          sid: path.AccountSID
          ad: path.AdId
          name: requestBody.Name
          type: requestBody.AdType
          campaign: requestBody.CampaignId
          lang: requestBody.Language
      - text: Change existing ad {ad}'s landing page to {landing}.
        slots:
          ad: path.AdId
          landing: requestBody.LandingPage
      method: generated
      generated: '2026-09-26'
- target: $.paths['/Mediapartners/{AccountSID}/Ads'].get
  update:
    x-apievangelist-phrasing:
      intent: List ads available to a partner
      effect: read
      questions:
      - What ads can I promote as a partner?
      - Is there a way for a partner to see only mobile-ready ads for a deal?
      instructions:
      - text: List the ads available to partner account {sid}.
        slots:
          sid: path.AccountSID
      - text: Show ads I can promote from campaign {campaign} for deal {deal}.
        slots:
          campaign: query.CampaignId
          deal: query.DealId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/Mediapartners/{AccountSID}/Ads/{Id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve an ad as a partner
      effect: read
      questions:
      - What details does a partner get about a single ad?
      - Can I check an ad's details before promoting it?
      instructions:
      - text: Retrieve ad {id} for partner account {sid}.
        slots:
          sid: path.AccountSID
          id: path.Id
      - text: Show me the details of promotable ad {id}.
        slots:
          id: path.Id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/Mediapartners/{AccountSID}/Ads/{Id}/Code'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an ad's HTML code
      effect: read
      questions:
      - How do I get the HTML embed code for an ad?
      - Can I append a sub ID to the tracking link inside an ad's HTML?
      instructions:
      - text: Get the HTML code for ad {id} in account {sid}.
        slots:
          sid: path.AccountSID
          id: path.Id
      - text: Give me ad {id}'s HTML snippet with subId1 set to {sub}.
        slots:
          id: path.Id
          sub: query.subId1
      method: generated
      generated: '2026-09-26'
- target: $.paths['/Mediapartners/{AccountSID}/Ads/{Id}/IFrameCode'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an ad's iframe code
      effect: read
      questions:
      - Is there an iframe version of an ad I can drop into my site?
      - Can the iframe code for an ad point at a custom landing page?
      instructions:
      - text: Get the iframe embed code for ad {id} in account {sid}.
        slots:
          sid: path.AccountSID
          id: path.Id
      - text: Produce an iframe for ad {id} landing on {landing}.
        slots:
          id: path.Id
          landing: query.landingPage
      method: generated
      generated: '2026-09-26'
- target: $.paths['/Mediapartners/{AccountSID}/Ads/{Id}/TrackingLink'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an ad's tracking link
      effect: read
      questions:
      - What's the tracking link for a specific ad?
      - Can I add a shared ID to an ad's tracking URL?
      instructions:
      - text: Get the tracking link for ad {id} in account {sid}.
        slots:
          sid: path.AccountSID
          id: path.Id
      - text: Build ad {id}'s tracking URL with shared ID {shared}.
        slots:
          id: path.Id
          shared: query.sharedId
      method: generated
      generated: '2026-09-26'