# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Surfe Companies API
  version: 1.0.0
extends: openapi/surfe-companies-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: 3
- target: $.paths['/companies/search'].post
  update:
    x-apievangelist-phrasing:
      intent: Search companies matching ICP filters
      effect: read
      questions:
      - How do I find companies in a given industry with a certain employee count?
      - Can I search for companies by revenue, location and keywords?
      - Which companies match my ideal customer profile criteria?
      - Why would a company search come back with a 402 error?
      instructions:
      - text: 'Find up to {limit} companies matching these filters: {filters}.'
        slots:
          limit: requestBody.limit
          filters: requestBody.filters
      - text: Get the next page of company search results using token {pageToken} with filters {filters}, {limit} per page.
        slots:
          pageToken: requestBody.pageToken
          filters: requestBody.filters
          limit: requestBody.limit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/companies/enrich'].post
  update:
    x-apievangelist-phrasing:
      intent: Start a bulk company enrichment job
      effect: write
      questions:
      - Can I enrich a list of company domains with firmographic data in bulk?
      - What do I need to start enriching companies by domain?
      - Is there a way to get a webhook when a company enrichment job finishes?
      instructions:
      - text: 'Start enriching these companies by domain: {companies}.'
        slots:
          companies: requestBody.companies
      - text: Kick off a company enrichment for {companies} and notify me via {notificationOptions} when it's done.
        slots:
          companies: requestBody.companies
          notificationOptions: requestBody.notificationOptions
      method: generated
      generated: '2026-09-26'
- target: $.paths['/companies/enrich/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a company enrichment job's results
      effect: read
      questions:
      - Has my company enrichment job finished yet?
      - Where do I get the firmographic results of a company enrichment I already started?
      instructions:
      - text: Check the status of company enrichment job {id}.
        slots:
          id: path.id
      - text: Fetch the enriched company results for job {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'