# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Spade Card Enrichment API
  version: 1.0.0
extends: openapi/spade-card-enrichment-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: 10
- target: $.paths['/transactions/cards/enrich'].post
  update:
    x-apievangelist-phrasing:
      intent: Enrich a single card transaction
      effect: write
      questions:
      - How do I turn a raw card swipe into a clean merchant name, logo and category with Spade?
      - Which optional fields like acquirer ID or card BIN improve the match on one card transaction?
      - Can I get my own custom attributes echoed back when I enrich a card purchase?
      instructions:
      - text: Enrich the card transaction from user {userId} for {amount} {currencyCode} at merchant {merchantName}, MCC {categoryCode}, on {occurredAt}.
        slots:
          userId: requestBody.userId
          amount: requestBody.amount
          currencyCode: requestBody.currencyCode
          merchantName: requestBody.merchantName
          categoryCode: requestBody.categoryCode
          occurredAt: requestBody.occurredAt
      - text: Enrich card purchase {transactionId} made at {location} and tag it with program {programId}.
        slots:
          transactionId: requestBody.transactionId
          location: requestBody.location
          programId: requestBody.programId
      - text: Identify the merchant behind card swipe {merchantName} using acquirer ID {acquirerId}.
        slots:
          merchantName: requestBody.merchantName
          acquirerId: requestBody.acquirerId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/transactions/cards/enrich/parse'].post
  update:
    x-apievangelist-phrasing:
      intent: Enrich a card transaction from a raw DE43 field
      effect: write
      questions:
      - Can I send the unparsed DE43 field instead of splitting out merchant name and city myself?
      - What happens when the DE43 string conflicts with the merchant name I also pass in?
      - Is there a card enrichment call that parses a DE43 message for one transaction?
      instructions:
      - text: Parse DE43 message {de43} and enrich that card transaction for user {userId}, {amount} {currencyCode} on {occurredAt}.
        slots:
          de43: requestBody.de43
          userId: requestBody.userId
          amount: requestBody.amount
          currencyCode: requestBody.currencyCode
          occurredAt: requestBody.occurredAt
      - text: Enrich the card swipe with raw DE43 {de43} and MCC {categoryCode} at {location}.
        slots:
          de43: requestBody.de43
          categoryCode: requestBody.categoryCode
          location: requestBody.location
      method: generated
      generated: '2026-10-01'
- target: $.paths['/batches/transactions/cards/enrich'].post
  update:
    x-apievangelist-phrasing:
      intent: Submit a batch of card transactions for enrichment
      effect: write
      questions:
      - How do I enrich thousands of card transactions in one job instead of one at a time?
      - Can a card enrichment batch call my URL when the job finishes?
      - What is the maximum number of card transactions in a single batch submission?
      - Can I get a small set of card transactions enriched inline without waiting on a batch job?
      instructions:
      - text: Submit these card transactions {transactions} as an enrichment batch and notify {callbackUrl} when done.
        slots:
          transactions: requestBody.transactions
          callbackUrl: requestBody.callbackUrl
      - text: Enrich this microbatch of card transactions {transactions} synchronously ({synchronous}).
        slots:
          transactions: requestBody.transactions
          synchronous: query.synchronous
      method: generated
      generated: '2026-10-01'
- target: $.paths['/batches/transactions/cards/enrich'].options
  update:
    x-apievangelist-phrasing:
      intent: Check the synchronous cap for card batch enrichment
      effect: read
      questions:
      - What is the current synchronousMax for enriching card transaction batches inline?
      - How many card transactions can I send in one synchronous microbatch right now?
      instructions:
      - text: Fetch the current synchronous item cap for the card batch enrichment endpoint.
      - text: Look up the metadata for card transaction batch enrichment.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/batches/transactions/cards/enrich/parse'].post
  update:
    x-apievangelist-phrasing:
      intent: Submit a batch of DE43 card transactions
      effect: write
      questions:
      - Can I batch-enrich card transactions that only carry raw DE43 strings?
      - Do batched DE43 card transactions still need merchant name and city fields?
      instructions:
      - text: Submit the DE43 card transactions {transactions} as a parse-and-enrich batch, calling {callbackUrl} on completion.
        slots:
          transactions: requestBody.transactions
          callbackUrl: requestBody.callbackUrl
      - text: Parse and enrich this small set of DE43 card swipes {transactions} inline with synchronous={synchronous}.
        slots:
          transactions: requestBody.transactions
          synchronous: query.synchronous
      method: generated
      generated: '2026-10-01'
- target: $.paths['/batches/transactions/cards/enrich/parse'].options
  update:
    x-apievangelist-phrasing:
      intent: Check the synchronous cap for DE43 batch enrichment
      effect: read
      questions:
      - What is the inline item limit for batch DE43 parse enrichment of card transactions?
      - Where can I fetch the synchronousMax for the card parse batch endpoint?
      instructions:
      - text: Get the current synchronous cap for the DE43 card parse batch endpoint.
      - text: Read the metadata for batch card enrichment with DE43 parsing.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/batches/{cardEnrichmentBatchId}/results'].get
  update:
    x-apievangelist-phrasing:
      intent: Get results of a card enrichment batch
      effect: read
      questions:
      - How do I download the enriched transactions once my card batch job is finished?
      - Where do the results of a batch card enrichment job come back?
      instructions:
      - text: Fetch the enriched results of card batch {cardEnrichmentBatchId}.
        slots:
          cardEnrichmentBatchId: path.cardEnrichmentBatchId
      - text: Pull the output of card enrichment job {cardEnrichmentBatchId}.
        slots:
          cardEnrichmentBatchId: path.cardEnrichmentBatchId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/batches/{cardEnrichmentBatchId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check the status of a card enrichment batch
      effect: read
      questions:
      - Is my batch card enrichment job still running or has it completed?
      - How can I poll progress on a card transaction batch I submitted?
      instructions:
      - text: Check whether card batch {cardEnrichmentBatchId} has finished.
        slots:
          cardEnrichmentBatchId: path.cardEnrichmentBatchId
      - text: Show the job status for card enrichment batch {cardEnrichmentBatchId}.
        slots:
          cardEnrichmentBatchId: path.cardEnrichmentBatchId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/transactions/enrich'].post
  update:
    x-apievangelist-phrasing:
      intent: Enrich a card transaction via the legacy endpoint
      effect: write
      questions:
      - Does the old /transactions/enrich card endpoint still work?
      - My integration calls the legacy transaction enrich path; what does it map to now?
      instructions:
      - text: Enrich a card transaction through the deprecated /transactions/enrich alias.
      - text: Send this card transaction to the legacy enrich endpoint my old integration uses.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/transactions/enrich/parse'].post
  update:
    x-apievangelist-phrasing:
      intent: Enrich a DE43 card transaction via the legacy endpoint
      effect: write
      questions:
      - Is the legacy /transactions/enrich/parse DE43 endpoint still supported?
      - What replaced the old DE43 parse path for card enrichment?
      instructions:
      - text: Enrich a DE43 card transaction through the deprecated /transactions/enrich/parse alias.
      - text: Send this raw DE43 swipe to the legacy parse endpoint my old code still calls.
      method: generated
      generated: '2026-10-01'