# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Impact Actions API
  version: 1.0.0
extends: openapi/impact-actions-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: 12
- target: $.paths['/Advertisers/{AccountSID}/Actions'].get
  update:
    x-apievangelist-phrasing:
      intent: List actions recorded for a brand's program
      effect: read
      questions:
      - Which conversions has my brand program recorded as actions over the last month?
      - Can I filter the brand-side action list by state, like only approved or reversed actions?
      - How far back can a brand pull actions — is there a limit on StartDate?
      instructions:
      - text: As brand account {account}, list actions for program {campaign} between {start} and {end}.
        slots:
          account: path.AccountSID
          campaign: query.CampaignId
          start: query.StartDate
          end: query.EndDate
      - text: Show brand account {account}'s actions in program {campaign} with state {state}.
        slots:
          account: path.AccountSID
          campaign: query.CampaignId
          state: query.State
      - text: List brand-side actions for program {campaign} in account {account} that lock between {lock_start} and {lock_end}.
        slots:
          account: path.AccountSID
          campaign: query.CampaignId
          lock_start: query.LockingDateStart
          lock_end: query.LockingDateEnd
      method: generated
      generated: '2026-09-26'
- target: $.paths['/Advertisers/{AccountSID}/Actions'].put
  update:
    x-apievangelist-phrasing:
      intent: Update an action or its line items
      effect: write
      questions:
      - Can I change the amount or quantity on a line item of an action a partner already earned?
      - What do I pass to modify an action's customer status after it was recorded?
      - Is it possible to adjust an action by order ID instead of the action ID?
      instructions:
      - text: In brand account {account}, update action {action} to customer status {status}.
        slots:
          account: path.AccountSID
          action: requestBody.ActionId
          status: requestBody.CustomerStatus
      - text: Change the quantity of item {sku} on action {action} to {qty} in account {account}.
        slots:
          account: path.AccountSID
          action: requestBody.ActionId
          sku: requestBody.Sku
          qty: requestBody.Quantity
      - text: Adjust the amount on order {order} for tracker {tracker} to {amount} with reason {reason} in account {account}.
        slots:
          account: path.AccountSID
          order: requestBody.OrderId
          tracker: requestBody.ActionTrackerId
          amount: requestBody.Amount
          reason: requestBody.Reason
      method: generated
      generated: '2026-09-26'
- target: $.paths['/Advertisers/{AccountSID}/Actions'].delete
  update:
    x-apievangelist-phrasing:
      intent: Reverse an action and cancel its payout
      effect: destructive
      questions:
      - How do I reverse a fraudulent conversion so the partner doesn't get paid for it?
      - Can I cancel a pending partner payout by reversing the order it came from?
      - What disposition code is needed when reversing an action?
      instructions:
      - text: Reverse action {action} in brand account {account} with disposition code {code}.
        slots:
          account: path.AccountSID
          action: requestBody.ActionId
          code: requestBody.DispositionCode
      - text: Reverse order {order} on action tracker {tracker} in account {account} using disposition {code}.
        slots:
          account: path.AccountSID
          order: requestBody.OrderId
          tracker: requestBody.ActionTrackerId
          code: requestBody.DispositionCode
      method: generated
      generated: '2026-09-26'
- target: $.paths['/Advertisers/{AccountSID}/Actions/{ActionId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a brand action's details
      effect: read
      questions:
      - Where can a brand see the full record of one specific action by its ID?
      - What details does the brand API return for a single tracked action?
      instructions:
      - text: As brand account {account}, get the details of action {action}.
        slots:
          account: path.AccountSID
          action: path.ActionId
      - text: Pull brand-side action {action} from account {account}.
        slots:
          account: path.AccountSID
          action: path.ActionId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/Advertisers/{AccountSID}/Actions/{ActionId}/Items'].get
  update:
    x-apievangelist-phrasing:
      intent: List the line items in a brand action
      effect: read
      questions:
      - Which products were part of an order a partner drove for my brand?
      - Can a brand see every line item inside one action in the order it was recorded?
      instructions:
      - text: As brand account {account}, list the line items on action {action}.
        slots:
          account: path.AccountSID
          action: path.ActionId
      - text: Show brand account {account} which SKUs were in action {action}.
        slots:
          account: path.AccountSID
          action: path.ActionId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/Advertisers/{AccountSID}/Actions/{ActionId}/Items/{Sku}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one line item of a brand action by SKU
      effect: read
      questions:
      - Can a brand look up a single product line inside an action using its SKU?
      - What did the brand record for one SKU on a specific action?
      instructions:
      - text: As brand account {account}, get item {sku} on action {action}.
        slots:
          account: path.AccountSID
          action: path.ActionId
          sku: path.Sku
      - text: Fetch the brand-side line for SKU {sku} from action {action} in account {account}.
        slots:
          account: path.AccountSID
          action: path.ActionId
          sku: path.Sku
      method: generated
      generated: '2026-09-26'
- target: $.paths['/Mediapartners/{AccountSID}/Actions'].get
  update:
    x-apievangelist-phrasing:
      intent: List actions attributed to a partner
      effect: read
      questions:
      - Which conversions have been credited to me as a partner in the past week?
      - Is there a 45-day limit on the date range when a partner lists their actions?
      - Can a partner narrow their action list to a single program or state?
      instructions:
      - text: As partner account {account}, list my actions from {start} to {end}.
        slots:
          account: path.AccountSID
          start: query.StartDate
          end: query.EndDate
      - text: Show partner actions in account {account} for program {campaign} in state {state}.
        slots:
          account: path.AccountSID
          campaign: query.CampaignId
          state: query.State
      - text: List my partner actions in account {account} from the last 7 days.
        slots:
          account: path.AccountSID
      method: generated
      generated: '2026-09-26'
- target: $.paths['/Mediapartners/{AccountSID}/Actions/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve an action credited to a partner
      effect: read
      questions:
      - As a partner, how can I see the full details of one action I earned?
      - What does a partner get back when fetching a single action by ID?
      instructions:
      - text: As partner account {account}, retrieve action {id}.
        slots:
          account: path.AccountSID
          id: path.id
      - text: Get my partner-side action {id} in account {account}.
        slots:
          account: path.AccountSID
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/Mediapartners/{AccountSID}/Actions/{id}/Items'].get
  update:
    x-apievangelist-phrasing:
      intent: List items in an action credited to a partner
      effect: read
      questions:
      - Which products did the customer buy in a sale credited to me as a partner?
      - Can a partner list every item within one of their actions?
      instructions:
      - text: As partner account {account}, list all items in action {id}.
        slots:
          account: path.AccountSID
          id: path.id
      - text: Show partner account {account} the products in my action {id}.
        slots:
          account: path.AccountSID
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/Mediapartners/{AccountSID}/Actions/{actionId}/Items/{sku}'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve a partner action item by SKU
      effect: read
      questions:
      - As a partner, can I pull the details of one SKU from an action I earned?
      - What commission detail is on a specific product line of a partner action?
      instructions:
      - text: As partner account {account}, retrieve item {sku} from action {action}.
        slots:
          account: path.AccountSID
          action: path.actionId
          sku: path.sku
      - text: Get the partner-side line for SKU {sku} on action {action} in account {account}.
        slots:
          account: path.AccountSID
          action: path.actionId
          sku: path.sku
      method: generated
      generated: '2026-09-26'
- target: $.paths['/Mediapartners/{AccountSID}/ActionUpdates'].get
  update:
    x-apievangelist-phrasing:
      intent: List changes to a partner's actions
      effect: read
      questions:
      - How do I sync state and payout changes on my partner actions into my own system?
      - Which of my partner actions changed state or payout this week?
      - Should a partner poll action updates, or are postbacks recommended instead?
      instructions:
      - text: As partner account {account}, list action updates from {start} to {end}.
        slots:
          account: path.AccountSID
          start: query.StartDate
          end: query.EndDate
      - text: Show partner action updates in account {account} for program {campaign} with state {state}.
        slots:
          account: path.AccountSID
          campaign: query.CampaignId
          state: query.State
      method: generated
      generated: '2026-09-26'
- target: $.paths['/Mediapartners/{AccountSID}/ActionUpdates/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve one change record on a partner action
      effect: read
      questions:
      - Can a partner see exactly what changed in a single action update record?
      - What does one action update entry contain for a partner?
      instructions:
      - text: As partner account {account}, retrieve action update {id}.
        slots:
          account: path.AccountSID
          id: path.id
      - text: Get the partner action change record {id} in account {account}.
        slots:
          account: path.AccountSID
          id: path.id
      method: generated
      generated: '2026-09-26'