# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Talon One Referrals API
  version: 1.0.0
extends: openapi/talon-one-referrals-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: 8
- target: $.paths['/v1/referrals'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a referral code for an advocate
      effect: write
      questions:
      - How do I give one customer a referral code they can share with friends?
      - Can a referral code have a usage limit and an expiry date?
      instructions:
      - text: Create a referral code for advocate {advocateProfileIntegrationId} in campaign {campaignId}.
        slots:
          advocateProfileIntegrationId: requestBody.advocateProfileIntegrationId
          campaignId: requestBody.campaignId
      - text: Create a referral for advocate {advocateProfileIntegrationId} in campaign {campaignId} that expires on {expiryDate}.
        slots:
          advocateProfileIntegrationId: requestBody.advocateProfileIntegrationId
          campaignId: requestBody.campaignId
          expiryDate: requestBody.expiryDate
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/referrals_for_multiple_advocates'].post
  update:
    x-apievangelist-phrasing:
      intent: Create referral codes for many advocates at once
      effect: write
      questions:
      - Can I generate unique referral codes for a whole list of customers in one request?
      - How do I control the characters and pattern of bulk-generated referral codes?
      instructions:
      - text: Create referral codes in campaign {campaignId} for advocates {advocateProfileIntegrationIds}.
        slots:
          campaignId: requestBody.campaignId
          advocateProfileIntegrationIds: requestBody.advocateProfileIntegrationIds
      - text: Generate codes for advocates {advocateProfileIntegrationIds} in campaign {campaignId} using pattern {referralPattern}.
        slots:
          advocateProfileIntegrationIds: requestBody.advocateProfileIntegrationIds
          campaignId: requestBody.campaignId
          referralPattern: requestBody.referralPattern
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/applications/{applicationId}/campaigns/{campaignId}/referrals/{referralId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a referral
      effect: write
      questions:
      - How do I extend the expiry date of an existing referral code?
      - Can I change the usage limit or assigned friend on a referral after it's created?
      instructions:
      - text: Set the expiry of referral {referralId} in campaign {campaignId}, Application {applicationId}, to {expiryDate}.
        slots:
          referralId: path.referralId
          campaignId: path.campaignId
          applicationId: path.applicationId
          expiryDate: requestBody.expiryDate
      - text: Change referral {referralId}'s usage limit to {usageLimit} in campaign {campaignId} of Application {applicationId}.
        slots:
          referralId: path.referralId
          usageLimit: requestBody.usageLimit
          campaignId: path.campaignId
          applicationId: path.applicationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/applications/{applicationId}/campaigns/{campaignId}/referrals/{referralId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a referral
      effect: destructive
      questions:
      - How do I revoke a referral code that's being abused?
      - Can I delete a single referral from a campaign?
      instructions:
      - text: Delete referral {referralId} from campaign {campaignId} in Application {applicationId}.
        slots:
          referralId: path.referralId
          campaignId: path.campaignId
          applicationId: path.applicationId
      - text: Remove referral code {referralId} in campaign {campaignId}, Application {applicationId}.
        slots:
          referralId: path.referralId
          campaignId: path.campaignId
          applicationId: path.applicationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/applications/{applicationId}/campaigns/{campaignId}/referrals/no_total'].get
  update:
    x-apievangelist-phrasing:
      intent: List a campaign's referrals
      effect: read
      questions:
      - Which referral codes exist in a campaign, and which are still usable?
      - Can I list all the referrals one advocate has created?
      instructions:
      - text: List the referrals in campaign {campaignId} of Application {applicationId}.
        slots:
          campaignId: path.campaignId
          applicationId: path.applicationId
      - text: Show referrals by advocate {advocate} in campaign {campaignId}, Application {applicationId}.
        slots:
          advocate: query.advocate
          campaignId: path.campaignId
          applicationId: path.applicationId
      - text: Look up referral code {code} in campaign {campaignId} of Application {applicationId}.
        slots:
          code: query.code
          campaignId: path.campaignId
          applicationId: path.applicationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/applications/{applicationId}/profile/{integrationId}/friends'].get
  update:
    x-apievangelist-phrasing:
      intent: List friends a customer has referred
      effect: read
      questions:
      - Who has a particular customer successfully referred?
      - How many friends has one advocate brought into my Application?
      instructions:
      - text: List the friends referred by customer {integrationId} in Application {applicationId}.
        slots:
          integrationId: path.integrationId
          applicationId: path.applicationId
      - text: Show who advocate {integrationId} referred in Application {applicationId}, with the total count.
        slots:
          integrationId: path.integrationId
          applicationId: path.applicationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/applications/{applicationId}/export_referrals'].get
  update:
    x-apievangelist-phrasing:
      intent: Export referrals to CSV
      effect: read
      questions:
      - Can I download all referral codes in an Application as a spreadsheet?
      - How do I export only the valid referrals from one campaign or batch?
      instructions:
      - text: Export the referrals of Application {applicationId} to CSV.
        slots:
          applicationId: path.applicationId
      - text: Download referrals from campaign {campaignId} in Application {applicationId} created after {createdAfter}.
        slots:
          campaignId: query.campaignId
          applicationId: path.applicationId
          createdAfter: query.createdAfter
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/applications/{applicationId}/campaigns/{campaignId}/import_referrals'].post
  update:
    x-apievangelist-phrasing:
      intent: Import referral codes from a CSV file
      effect: write
      questions:
      - How do I bring existing referral codes from another system into a campaign?
      - What columns does a referral import CSV need?
      instructions:
      - text: Import the referrals in {upFile} into campaign {campaignId} of Application {applicationId}.
        slots:
          upFile: requestBody.upFile
          campaignId: path.campaignId
          applicationId: path.applicationId
      - text: Upload referral CSV {upFile} to campaign {campaignId}, Application {applicationId}.
        slots:
          upFile: requestBody.upFile
          campaignId: path.campaignId
          applicationId: path.applicationId
      method: generated
      generated: '2026-09-26'