# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Hunter Leads API
  version: 1.0.0
extends: openapi/hunter-leads-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: 6
- target: $.paths['/leads'].get
  update:
    x-apievangelist-phrasing:
      intent: List the leads saved in my account
      effect: read
      questions:
      - How do I pull every lead I've saved in Hunter?
      - Can I filter my saved leads by company or by the list they belong to?
      - What's the most leads I can get back in one page of results?
      instructions:
      - text: List my saved leads.
      - text: Show the saved leads in leads list {leads_list_id}.
        slots:
          leads_list_id: query.leads_list_id
      - text: Find my saved leads who work at {company}, {limit} at a time.
        slots:
          company: query.company
          limit: query.limit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/leads'].put
  update:
    x-apievangelist-phrasing:
      intent: Create a lead or update it if the email exists
      effect: write
      questions:
      - Can I save a lead without creating a duplicate if that email is already in the list?
      - Is there a way to add-or-update a lead by email address in one call?
      instructions:
      - text: Upsert {email} into leads list {leads_list_id}, updating it if that email is already there.
        slots:
          email: requestBody.email
          leads_list_id: requestBody.leads_list_id
      - text: Save {email} as {position} at {company}, or refresh the existing lead with that email.
        slots:
          email: requestBody.email
          position: requestBody.position
          company: requestBody.company
      method: generated
      generated: '2026-09-26'
- target: $.paths['/leads'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a new lead
      effect: write
      questions:
      - How do I add a brand-new prospect to my leads?
      - What details can I record when I create a new lead, like LinkedIn URL or notes?
      instructions:
      - text: Create a new lead for {first_name} {last_name} with email {email}.
        slots:
          first_name: requestBody.first_name
          last_name: requestBody.last_name
          email: requestBody.email
      - text: Add a new lead {email} from {company} with the note {notes}.
        slots:
          email: requestBody.email
          company: requestBody.company
          notes: requestBody.notes
      method: generated
      generated: '2026-09-26'
- target: $.paths['/leads/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the details of one lead
      effect: read
      questions:
      - How can I look up everything stored on a single lead by its ID?
      - What information comes back when I fetch one specific lead?
      instructions:
      - text: Show me lead {id}.
        slots:
          id: path.id
      - text: Fetch the full record for lead {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/leads/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update an existing lead by ID
      effect: write
      questions:
      - How do I change the job title or company on a lead I already saved?
      - Can I move an existing lead into a different leads list?
      instructions:
      - text: Update lead {id} so their position is {position}.
        slots:
          id: path.id
          position: requestBody.position
      - text: Move lead {id} into leads list {leads_list_id}.
        slots:
          id: path.id
          leads_list_id: requestBody.leads_list_id
      - text: Change the phone number on lead {id} to {phone_number}.
        slots:
          id: path.id
          phone_number: requestBody.phone_number
      method: generated
      generated: '2026-09-26'
- target: $.paths['/leads/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a lead
      effect: destructive
      questions:
      - How do I permanently remove a lead from my account?
      - Can I delete a single lead by its ID?
      instructions:
      - text: Delete lead {id}.
        slots:
          id: path.id
      - text: Remove lead {id} from my account.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'