# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Spade Feedback and Reporting API
  version: 1.0.0
extends: openapi/spade-feedback-and-reporting-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-01'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 5
- target: $.paths['/transactions/report'].post
  update:
    x-apievangelist-phrasing:
      intent: Report an incorrect card enrichment
      effect: write
      questions:
      - How do I tell Spade an enriched card transaction got the wrong merchant or category?
      - Can I flag that only the location on an enrichment was wrong?
      - What do I need to send to report a bad enrichment result?
      instructions:
      - text: 'Report enrichment {enrichmentId} as incorrect: {errorDescription}.'
        slots:
          enrichmentId: requestBody.enrichmentId
          errorDescription: requestBody.errorDescription
      - text: Flag the category on enrichment {enrichmentId} as wrong ({incorrectCategoryDescription}) with note {errorDescription}.
        slots:
          enrichmentId: requestBody.enrichmentId
          incorrectCategoryDescription: requestBody.incorrectCategoryDescription
          errorDescription: requestBody.errorDescription
      - text: Mark the counterparty on enrichment {enrichmentId} as incorrect because {incorrectCounterpartyDescription}; summary {errorDescription}.
        slots:
          enrichmentId: requestBody.enrichmentId
          incorrectCounterpartyDescription: requestBody.incorrectCounterpartyDescription
          errorDescription: requestBody.errorDescription
      method: generated
      generated: '2026-10-01'
- target: $.paths['/enrichments/{enrichmentId}/chargeback'].post
  update:
    x-apievangelist-phrasing:
      intent: Report a chargeback on an enriched transaction
      effect: write
      questions:
      - How do I let Spade know a cardholder disputed a transaction with a chargeback?
      - Can I update a chargeback's state as the dispute moves along?
      - Can I mark a chargeback as fraud-related and say what kind of fraud?
      instructions:
      - text: Record a chargeback in state {state} on enrichment {enrichmentId}.
        slots:
          state: requestBody.state
          enrichmentId: path.enrichmentId
      - text: Report a {state} chargeback on enrichment {enrichmentId} as fraud of type {fraudType}.
        slots:
          state: requestBody.state
          enrichmentId: path.enrichmentId
          fraudType: requestBody.fraudType
      method: generated
      generated: '2026-10-01'
- target: $.paths['/enrichments/{enrichmentId}/decline'].post
  update:
    x-apievangelist-phrasing:
      intent: Report a card decline on an enriched transaction
      effect: write
      questions:
      - How do I send Spade the decline code when a card authorization is refused?
      - Can I note that a declined card transaction was suspected fraud?
      instructions:
      - text: Report a card decline with code {declineCode} on enrichment {enrichmentId}.
        slots:
          declineCode: requestBody.declineCode
          enrichmentId: path.enrichmentId
      - text: 'Log that enrichment {enrichmentId} was declined at {occurredAt}: {declineDescription}.'
        slots:
          enrichmentId: path.enrichmentId
          occurredAt: requestBody.occurredAt
          declineDescription: requestBody.declineDescription
      method: generated
      generated: '2026-10-01'
- target: $.paths['/enrichments/{enrichmentId}/refund'].post
  update:
    x-apievangelist-phrasing:
      intent: Report a refund on an enriched transaction
      effect: write
      questions:
      - How do I tell Spade a merchant refunded a transaction it already enriched?
      - Can I attach notes and a timestamp when reporting a refund?
      instructions:
      - text: Report a refund on enrichment {enrichmentId}.
        slots:
          enrichmentId: path.enrichmentId
      - text: Record that enrichment {enrichmentId} was refunded at {occurredAt} with note {refundNotes}.
        slots:
          enrichmentId: path.enrichmentId
          occurredAt: requestBody.occurredAt
          refundNotes: requestBody.refundNotes
      method: generated
      generated: '2026-10-01'
- target: $.paths['/enrichments/{enrichmentId}/fraud'].post
  update:
    x-apievangelist-phrasing:
      intent: Report suspected fraud on a transaction
      effect: write
      questions:
      - Where do I report fraud that didn't involve a chargeback, decline or refund?
      - What fraud types can I attach to an enriched transaction?
      instructions:
      - text: Flag enrichment {enrichmentId} as suspected fraud of type {fraudType}.
        slots:
          enrichmentId: path.enrichmentId
          fraudType: requestBody.fraudType
      - text: Report standalone fraud on enrichment {enrichmentId} with notes {fraudNotes}.
        slots:
          enrichmentId: path.enrichmentId
          fraudNotes: requestBody.fraudNotes
      method: generated
      generated: '2026-10-01'