# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Admin API V1 Salespersons API
  version: 1.0.0
extends: openapi/optimizely-salespersons-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: 11
- target: $.paths['/api/v1/admin/Salespersons'].get
  update:
    x-apievangelist-phrasing:
      intent: List salespersons
      effect: read
      questions:
      - Who are all the sales reps configured in my Optimizely commerce admin?
      - Can I filter salespersons to just outside reps?
      - Is there a way to sort sales reps by year-to-date sales?
      instructions:
      - text: List all salespersons.
      - text: Find salespersons matching {filter}.
        slots:
          filter: query.$filter
      - text: Show the top {top} salespersons ordered by {orderby}.
        slots:
          top: query.$top
          orderby: query.$orderby
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Salespersons'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a salesperson
      effect: write
      questions:
      - How do I add a new sales rep with their number, email and phone?
      - Can I set a maximum discount percent when creating a salesperson?
      instructions:
      - text: Create salesperson {name} with number {salespersonNumber} and email {email}.
        slots:
          name: requestBody.name
          salespersonNumber: requestBody.salespersonNumber
          email: requestBody.email
      - text: Add a new sales rep {name} reporting to sales manager {salesManagerId}.
        slots:
          name: requestBody.name
          salesManagerId: requestBody.salesManagerId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Salespersons({id})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one salesperson
      effect: read
      questions:
      - What contact details are on file for a specific sales rep?
      - How do I see one salesperson's margin and discount limits?
      instructions:
      - text: Get salesperson {id}.
        slots:
          id: path.id
      - text: Show sales rep {id} with only the fields {select}.
        slots:
          id: path.id
          select: query.$select
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Salespersons({id})'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a salesperson record
      effect: write
      questions:
      - How do I overwrite a sales rep's entire record in one request?
      - Can I replace all fields of a salesperson rather than patching a few?
      instructions:
      - text: Replace salesperson {id} with a full record named {name}, email {email}.
        slots:
          id: path.id
          name: requestBody.name
          email: requestBody.email
      - text: Overwrite the complete record for sales rep {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Salespersons({id})'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a salesperson
      effect: destructive
      questions:
      - How do I remove a single sales rep by ID?
      - Can I make a salesperson delete conditional on the record's ETag?
      instructions:
      - text: Delete salesperson {id}.
        slots:
          id: path.id
      - text: Delete sales rep {id} if the ETag still matches {ifMatch}.
        slots:
          id: path.id
          ifMatch: header.If-Match
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Salespersons({id})'].patch
  update:
    x-apievangelist-phrasing:
      intent: Partially update a salesperson
      effect: write
      questions:
      - Can I change just a sales rep's phone number or title?
      - How do I lower one salesperson's maximum discount percent?
      instructions:
      - text: Update the email of salesperson {id} to {email}.
        slots:
          id: path.id
          email: requestBody.email
      - text: Set the max discount for sales rep {id} to {maxDiscountPercent} percent.
        slots:
          id: path.id
          maxDiscountPercent: requestBody.maxDiscountPercent
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Salespersons/Default.Default()'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the default salesperson template
      effect: read
      questions:
      - What default values does a new salesperson record start with?
      - Is there a blank salesperson template I can fetch?
      instructions:
      - text: Fetch the default salesperson template.
      - text: Get default values for a new sales rep.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/salespersons/delete'].delete
  update:
    x-apievangelist-phrasing:
      intent: Bulk delete salespersons
      effect: destructive
      questions:
      - How do I delete several sales reps in one call?
      - Can I pass a list of IDs to remove multiple salespersons?
      instructions:
      - text: Bulk delete salespersons {ids}.
        slots:
          ids: query.ids
      - text: 'Remove all of these sales reps at once: {ids}.'
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/salespersons({key})/customerorders({customerorderKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an order handled by a salesperson
      effect: read
      questions:
      - How do I look up a specific customer order attributed to a sales rep?
      - Can I fetch one order from a salesperson's orders?
      instructions:
      - text: Get order {customerorderKey} for salesperson {key}.
        slots:
          customerorderKey: path.customerorderKey
          key: path.key
      - text: Show customer order {customerorderKey} under sales rep {key}.
        slots:
          customerorderKey: path.customerorderKey
          key: path.key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/salespersons({key})/customers({customerKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a customer assigned to a salesperson
      effect: read
      questions:
      - How do I check a particular customer on a sales rep's account list?
      - Can I pull one customer record through its assigned salesperson?
      instructions:
      - text: Get customer {customerKey} assigned to salesperson {key}.
        slots:
          customerKey: path.customerKey
          key: path.key
      - text: Show account {customerKey} from sales rep {key}'s customers.
        slots:
          customerKey: path.customerKey
          key: path.key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/salespersons({key})/customproperties({custompropertyKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a custom property of a salesperson
      effect: read
      questions:
      - How do I read a custom property stored on a sales rep?
      - Can I fetch one custom field value for a salesperson?
      instructions:
      - text: Get custom property {custompropertyKey} of salesperson {key}.
        slots:
          custompropertyKey: path.custompropertyKey
          key: path.key
      - text: Show custom field {custompropertyKey} on sales rep {key}.
        slots:
          custompropertyKey: path.custompropertyKey
          key: path.key
      method: generated
      generated: '2026-09-26'