# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Surfe People API
  version: 1.0.0
extends: openapi/surfe-people-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: 4
- target: $.paths['/people/search'].post
  update:
    x-apievangelist-phrasing:
      intent: Search people by persona and company filters
      effect: read
      questions:
      - How do I find prospects by job title and seniority at companies in a certain industry?
      - Can I limit how many people come back per company in a people search?
      - Which decision makers in a given department work at companies of a certain headcount?
      instructions:
      - text: Find up to {limit} people with persona filters {people} at companies matching {companies}.
        slots:
          limit: requestBody.limit
          people: requestBody.people
          companies: requestBody.companies
      - text: Search for {limit} prospects matching {people}, at most {peoplePerCompany} per company.
        slots:
          limit: requestBody.limit
          people: requestBody.people
          peoplePerCompany: requestBody.peoplePerCompany
      - text: Load the next page of people search results with token {pageToken}, {limit} per page.
        slots:
          pageToken: requestBody.pageToken
          limit: requestBody.limit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/people/enrich'].post
  update:
    x-apievangelist-phrasing:
      intent: Start a bulk people enrichment job
      effect: write
      questions:
      - How do I get verified emails and mobile numbers for a list of LinkedIn profiles?
      - Can I enrich contacts using just first name, last name and company domain?
      - What is the maximum number of people I can enrich in one bulk job?
      instructions:
      - text: Start enriching {people} to retrieve {include}.
        slots:
          people: requestBody.people
          include: requestBody.include
      - text: Kick off a people enrichment for {people} returning {include}, and notify me via {notificationOptions}.
        slots:
          people: requestBody.people
          include: requestBody.include
          notificationOptions: requestBody.notificationOptions
      method: generated
      generated: '2026-09-26'
- target: $.paths['/people/enrich/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a people enrichment job's results
      effect: read
      questions:
      - Is my contact enrichment job completed yet?
      - Where can I pick up the emails and phone numbers from a people enrichment I already started?
      instructions:
      - text: Check the status of people enrichment job {id}.
        slots:
          id: path.id
      - text: Get the enriched contact details from people enrichment job {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/people/find-by-email'].post
  update:
    x-apievangelist-phrasing:
      intent: Look up people from email addresses
      effect: read
      questions:
      - Can I look up who owns an email address and what company they work for?
      - What profile and firmographic data comes back when I enrich from a list of emails?
      instructions:
      - text: 'Find the person profiles behind these email addresses: {emails}.'
        slots:
          emails: requestBody.emails
      - text: Look up {emails} and tell me each person's company.
        slots:
          emails: requestBody.emails
      method: generated
      generated: '2026-09-26'