# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for api.peopledatalabs.com Person Endpoints API
  version: 1.0.0
extends: openapi/peopledatalabs-person-endpoints-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-01'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 6
- target: $.paths['/v5/person/enrich'].get
  update:
    x-apievangelist-phrasing:
      intent: Enrich one person's profile
      effect: read
      questions:
      - Can I get someone's full professional profile from their work email?
      - How do I require that an enriched person has a phone number before it counts as a match?
      - What minimum likelihood should a person match have before it's returned?
      instructions:
      - text: Enrich the person with email {email}.
        slots:
          email: query.email
      - text: Enrich {first_name} {last_name} who worked at {company}, requiring {required}.
        slots:
          first_name: query.first_name
          last_name: query.last_name
          company: query.company
          required: query.required
      - text: Enrich PDL person {pdl_id} and return only {data_include}.
        slots:
          pdl_id: query.pdl_id
          data_include: query.data_include
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v5/person/identify'].get
  update:
    x-apievangelist-phrasing:
      intent: Find every profile that could match an identity
      effect: read
      questions:
      - Which candidate profiles could belong to this phone number?
      - Can I get all possible matches for a person instead of just the single best one?
      instructions:
      - text: Identify all candidate profiles for phone {phone}.
        slots:
          phone: query.phone
      - text: List every possible profile for {name} in {location}.
        slots:
          name: query.name
          location: query.location
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v5/person/search'].get
  update:
    x-apievangelist-phrasing:
      intent: Search people with a GET query
      effect: read
      questions:
      - How do I find people by title and location with a GET search?
      - Can I restrict a person search to a particular dataset category?
      instructions:
      - text: Search people with SQL {sql} as a GET request.
        slots:
          sql: query.sql
      - text: Search the {dataset} dataset with Elasticsearch query {query} and return {size} people.
        slots:
          dataset: query.dataset
          query: query.query
          size: query.size
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v5/person/search'].post
  update:
    x-apievangelist-phrasing:
      intent: Search people with a POST body
      effect: read
      questions:
      - Can I send a long person search query in a JSON body?
      - How do I page a POST person search with an offset or scroll token?
      instructions:
      - text: POST the person search SQL {sql} and return {size} results.
        slots:
          sql: requestBody.sql
          size: requestBody.size
      - text: Continue my POST person search from scroll token {scroll_token}.
        slots:
          scroll_token: requestBody.scroll_token
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v5/person/retrieve/{person_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve a person by PDL ID
      effect: read
      questions:
      - How do I fetch a single person record when I already have their PDL ID?
      - Can I retrieve a stored person profile directly by its ID?
      instructions:
      - text: Retrieve person {person_id}.
        slots:
          person_id: path.person_id
      - text: Fetch the titlecased record for PDL ID {person_id}.
        slots:
          person_id: path.person_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v5/person/retrieve/bulk'].post
  update:
    x-apievangelist-phrasing:
      intent: Retrieve many people by PDL ID
      effect: read
      questions:
      - Can I pull a batch of person records in one call when I have their PDL IDs?
      - How many people can a bulk retrieve request include?
      instructions:
      - text: 'Bulk retrieve these PDL person IDs: {requests}.'
        slots:
          requests: requestBody.requests
      - text: Fetch all of the person IDs in {requests} in a single request.
        slots:
          requests: requestBody.requests
      method: generated
      generated: '2026-10-01'