# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for impact.com User API
  version: 1.0.0
extends: openapi/impact-user-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['/{tenant_alias}/user'].get
  update:
    x-apievangelist-phrasing:
      intent: Look up a user by referral code
      effect: read
      questions:
      - Who does this referral code belong to in my referral program?
      - Can I retrieve a user's details when all I have is their referral code?
      instructions:
      - text: In tenant {tenant}, look up the user with referral code {code} using my API key.
        slots:
          tenant: path.tenant_alias
          code: query.referralCode
      - text: Find the referral participant for code {code} in tenant {tenant}.
        slots:
          tenant: path.tenant_alias
          code: query.referralCode
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{tenant_alias}/user'].post
  update:
    x-apievangelist-phrasing:
      intent: Create or update a referral program user
      effect: write
      questions:
      - How do I add a participant to my referral program or update their details?
      - Does upserting a user also create the account it points to?
      instructions:
      - text: In tenant {tenant}, upsert user {id} on existing account {acct} with email {email}.
        slots:
          tenant: path.tenant_alias
          id: requestBody.id
          acct: requestBody.accountId
          email: requestBody.email
      - text: Save user {id} on account {acct} in tenant {tenant} with referral code {code}.
        slots:
          tenant: path.tenant_alias
          id: requestBody.id
          acct: requestBody.accountId
          code: requestBody.referralCode
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{tenant_alias}/account/{accountId}/user/{userId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Look up a user by ID
      effect: read
      questions:
      - What personal details are stored for a referral user, looked up by their ID?
      - Does the user lookup include rewards or referrals, or only the user's own info?
      instructions:
      - text: In tenant {tenant}, get user {user} on account {acct}.
        slots:
          tenant: path.tenant_alias
          acct: path.accountId
          user: path.userId
      - text: Show the profile of user {user} in account {acct}, tenant {tenant}.
        slots:
          tenant: path.tenant_alias
          acct: path.accountId
          user: path.userId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{tenant_alias}/account/{accountId}/user/{userId}/pii'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the personal data stored for a user
      effect: read
      questions:
      - What personally identifiable information does impact.com hold about one of my users?
      - Can I export a user's PII to answer a data privacy request?
      instructions:
      - text: In tenant {tenant}, pull the PII stored for user {user} on account {acct}.
        slots:
          tenant: path.tenant_alias
          acct: path.accountId
          user: path.userId
      - text: For a privacy request, get user {user}'s personal data on account {acct} in tenant {tenant}.
        slots:
          tenant: path.tenant_alias
          acct: path.accountId
          user: path.userId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{tenant_alias}/account/{accountId}/user/{userId}/block'].post
  update:
    x-apievangelist-phrasing:
      intent: Block a user from making referrals
      effect: write
      questions:
      - Can I stop a suspicious user from earning successful referrals?
      - What happens to a participant's referrals once they are blocked?
      instructions:
      - text: Block user {user} on account {acct} in tenant {tenant} from referring.
        slots:
          tenant: path.tenant_alias
          acct: path.accountId
          user: path.userId
      - text: Stop user {user} in account {acct}, tenant {tenant}, from making successful referrals.
        slots:
          tenant: path.tenant_alias
          acct: path.accountId
          user: path.userId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{tenant_alias}/account/{accountId}/user/{userId}/unblock'].post
  update:
    x-apievangelist-phrasing:
      intent: Unblock a user so they can refer again
      effect: write
      questions:
      - How can I lift a block on a referral participant?
      - Can a previously blocked user be allowed to refer again?
      instructions:
      - text: Unblock user {user} on account {acct} in tenant {tenant}.
        slots:
          tenant: path.tenant_alias
          acct: path.accountId
          user: path.userId
      - text: Restore referral privileges for user {user} in account {acct}, tenant {tenant}.
        slots:
          tenant: path.tenant_alias
          acct: path.accountId
          user: path.userId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{tenant_alias}/users'].get
  update:
    x-apievangelist-phrasing:
      intent: List users in referral programs
      effect: read
      questions:
      - Which participants are enrolled in my Advocate referral programs?
      - Can I search and page through all referral users?
      instructions:
      - text: List users in tenant {tenant}, {limit} at a time.
        slots:
          tenant: path.tenant_alias
          limit: query.limit
      - text: Search users in tenant {tenant} matching {query}.
        slots:
          tenant: path.tenant_alias
          query: query.query
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{tenant_alias}/open/account/{accountId}/user/{userId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Look up a user with share links (open endpoint)
      effect: read
      questions:
      - Can I fetch a referral user along with their share links through the open endpoint?
      - Which extra fields can the open user lookup return besides personal info?
      instructions:
      - text: Via the open endpoint in tenant {tenant}, get user {user} on account {acct} with their share links.
        slots:
          tenant: path.tenant_alias
          acct: path.accountId
          user: path.userId
      - text: Open-lookup user {user} on account {acct} in tenant {tenant} including fields {fields}.
        slots:
          tenant: path.tenant_alias
          acct: path.accountId
          user: path.userId
          fields: query.fields
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{tenant_alias}/open/account/{accountId}/user/{userId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Create or update a user and account (open endpoint)
      effect: write
      questions:
      - Can I update a referral participant and create their account in one call if it doesn't exist?
      - What does the open upsert do when the user already exists?
      instructions:
      - text: Upsert user {user} on account {acct} in tenant {tenant} via the open endpoint with email {email}.
        slots:
          tenant: path.tenant_alias
          acct: path.accountId
          user: path.userId
          email: requestBody.email
      - text: Via the open endpoint, update or create user {user} on account {acct} in tenant {tenant} with referred-by codes {codes}.
        slots:
          tenant: path.tenant_alias
          acct: path.accountId
          user: path.userId
          codes: requestBody.referredByCodes
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{tenant_alias}/open/account/{accountId}/user/{userId}'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a new user and account (open endpoint)
      effect: write
      questions:
      - How do I register a brand-new referral participant and their account together?
      - Does creating a user on the open endpoint need a write token or API key?
      instructions:
      - text: Create new user {user} with account {acct} in tenant {tenant} via the open endpoint, first name {first}.
        slots:
          tenant: path.tenant_alias
          acct: path.accountId
          user: path.userId
          first: requestBody.firstName
      - text: Sign up a new open-endpoint user {user} on new account {acct} in tenant {tenant} with email {email}.
        slots:
          tenant: path.tenant_alias
          acct: path.accountId
          user: path.userId
          email: requestBody.email
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{tenant_alias}/open/account/{accountId}/user/{userId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a user (open endpoint)
      effect: destructive
      questions:
      - Can I remove a referral user without deleting the account they belong to?
      - Is there a do-not-track option when deleting a user?
      instructions:
      - text: Delete user {user} from account {acct} in tenant {tenant} via the open endpoint.
        slots:
          tenant: path.tenant_alias
          acct: path.accountId
          user: path.userId
      - text: Delete open-endpoint user {user} on account {acct} in tenant {tenant} and set do-not-track to {dnt}.
        slots:
          tenant: path.tenant_alias
          acct: path.accountId
          user: path.userId
          dnt: query.doNotTrack
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{tenant_alias}/open/user'].get
  update:
    x-apievangelist-phrasing:
      intent: Find a user by referral code (open endpoint)
      effect: read
      questions:
      - Can a front end resolve a referral code to its user through the open endpoint?
      - Is the open lookup-by-code endpoint enabled by default?
      instructions:
      - text: Via the open endpoint in tenant {tenant}, find who owns referral code {code}.
        slots:
          tenant: path.tenant_alias
          code: query.referralCode
      - text: Open-lookup the user behind code {code} in tenant {tenant}.
        slots:
          tenant: path.tenant_alias
          code: query.referralCode
      method: generated
      generated: '2026-09-26'