API Evangelist conversational phrasing for Peopledatalabs Person API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Peopledatalabs Person API
  version: 1.0.0
extends: openapi/peopledatalabs-person-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: 12
- target: $.paths['/v5/person/subjectrequest'].get
  update:
    x-apievangelist-phrasing:
      intent: Download the list of opted-out person IDs
      effect: read
      questions:
      - Where can I get the PDL person IDs of people who opted out of the data?
      - Is there a CSV of opted-out profiles I should suppress from my records?
      instructions:
      - text: Download the CSV of person IDs that have opted out of People Data Labs data.
      - text: Fetch the opt-out subject request file so I can purge those person IDs from my copy.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v5/person/enrich'].get
  update:
    x-apievangelist-phrasing:
      intent: Enrich a person record with the v5 enrichment API
      effect: read
      questions:
      - Can I enrich a person by their PDL ID and get back only certain fields like names and emails?
      - What happens if I require that an enriched person record has a work email before it counts as a match?
      - Can v5 person enrichment tell me which of my inputs actually matched the profile?
      instructions:
      - text: Enrich PDL person {pdl_id} and include only the fields {data_include}.
        slots:
          pdl_id: query.pdl_id
          data_include: query.data_include
      - text: Run v5 enrichment for {name} at {company}, and return a match only if it has {required}.
        slots:
          name: query.name
          company: query.company
          required: query.required
      - text: Enrich the person with SHA-256 email hash {email_hash} and show which inputs matched.
        slots:
          email_hash: query.email_hash
      - text: Enrich the person with LinkedIn numeric ID {lid}, titlecased.
        slots:
          lid: query.lid
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v5/person/enrich/preview'].get
  update:
    x-apievangelist-phrasing:
      intent: Preview a person enrichment match
      effect: read
      questions:
      - Can I see a preview of a person record before paying for the full enrichment?
      - Is there a way to check whether someone would match without pulling their complete profile?
      instructions:
      - text: Get a preview record for the person with email {email} instead of the full enrichment.
        slots:
          email: query.email
      - text: Preview the enrichment match for {first_name} {last_name} in {locality}.
        slots:
          first_name: query.first_name
          last_name: query.last_name
          locality: query.locality
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v5/person/identify'].get
  update:
    x-apievangelist-phrasing:
      intent: Recover all related profiles for an identity
      effect: read
      questions:
      - How can I pull back every related profile for one identity using the v5 identify endpoint?
      - Can I identify all profiles tied to someone from their birth date and postal code?
      instructions:
      - text: Recover every related profile for the identity with email {email} using v5 identify.
        slots:
          email: query.email
      - text: Identify all profiles for {name} born {birth_date} living in postal code {postal_code}.
        slots:
          name: query.name
          birth_date: query.birth_date
          postal_code: query.postal_code
      - text: Find all related profiles for the person who attended {school} and lives in {region}.
        slots:
          school: query.school
          region: query.region
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v5/person/search'].get
  update:
    x-apievangelist-phrasing:
      intent: Search the person dataset with a GET query
      effect: read
      questions:
      - Can I limit a v5 person search to a specific dataset category like mobile phones or emails?
      - How do I page through more than 10,000 person search results with a scroll token on a GET request?
      instructions:
      - text: Search people with SQL {sql} in the {dataset} dataset as a GET request.
        slots:
          sql: query.sql
          dataset: query.dataset
      - text: Continue my GET person search using scroll token {scroll_token}.
        slots:
          scroll_token: query.scroll_token
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v5/person/search'].post
  update:
    x-apievangelist-phrasing:
      intent: Search the person dataset with a POST query
      effect: read
      questions:
      - Can a POST person search return up to 1,000 people per page?
      - Which form of the v5 person search should I use for long Elasticsearch queries sent by POST?
      instructions:
      - text: POST the Elasticsearch query {query} to v5 person search and return {size} people, up to 1000.
        slots:
          query: query.query
          size: query.size
      - text: Fetch the next batch of my POST person search with scroll token {scroll_token}.
        slots:
          scroll_token: query.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 pull a single person record when I already have their PDL ID?
      - Can I skip a retrieved person if their record hasn't changed since I last asked?
      instructions:
      - text: Retrieve the person with PDL ID {person_id}.
        slots:
          person_id: path.person_id
      - text: Retrieve person {person_id} only if {filter_updated} changed since my last request.
        slots:
          person_id: path.person_id
          filter_updated: query.filter_updated
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v5/person/retrieve/bulk'].post
  update:
    x-apievangelist-phrasing:
      intent: Retrieve up to 100 people by PDL ID
      effect: read
      questions:
      - Can I retrieve a batch of people at once when I already have their PDL IDs?
      - What's the most person IDs I can fetch in one bulk retrieve call?
      instructions:
      - text: 'Bulk retrieve these PDL person IDs in one call: {requests}.'
        slots:
          requests: requestBody.requests
      - text: Retrieve the person ID list {requests}, filtering out records where {filter_updated} has not changed.
        slots:
          requests: requestBody.requests
          filter_updated: query.filter_updated
      method: generated
      generated: '2026-10-01'
- target: $.paths['/person/enrich'].get
  update:
    x-apievangelist-phrasing:
      intent: Enrich one person's profile
      effect: read
      questions:
      - Can I get a full professional profile for someone from just their work email?
      - What does People Data Labs return when I enrich a person by phone number?
      - Is there a way to set a minimum match confidence before a person profile comes back?
      instructions:
      - text: Enrich the person with email {email} and return their single best-matching profile.
        slots:
          email: query.email
      - text: Look up the full profile for {first_name} {last_name} who works at {company}.
        slots:
          first_name: query.first_name
          last_name: query.last_name
          company: query.company
      - text: Enrich the person behind social profile URL {profile}, only if the match likelihood is at least {min_likelihood}.
        slots:
          profile: query.profile
          min_likelihood: query.min_likelihood
      method: generated
      generated: '2026-10-01'
- target: $.paths['/person/search'].get
  update:
    x-apievangelist-phrasing:
      intent: Search people with an SQL or Elasticsearch query
      effect: read
      questions:
      - How do I find every person who matches criteria like job title and location?
      - Can I write an SQL query to search the people dataset?
      - How many person profiles can one search page return, and how do I page past them?
      instructions:
      - text: Search person profiles with the SQL query {sql}.
        slots:
          sql: query.sql
      - text: Run the Elasticsearch query {query} against person profiles and return {size} results.
        slots:
          query: query.query
          size: query.size
      - text: Get the next page of people matching {sql}, starting at result {from}.
        slots:
          sql: query.sql
          from: query.from
      method: generated
      generated: '2026-10-01'
- target: $.paths['/person/identify'].get
  update:
    x-apievangelist-phrasing:
      intent: List likely person matches with likelihood scores
      effect: read
      questions:
      - Which candidate people could this email belong to, ranked by how likely each one is?
      - Can I see several possible matches with scores instead of a single enriched profile?
      instructions:
      - text: Identify the likely people behind phone number {phone} and show each match score.
        slots:
          phone: query.phone
      - text: List every possible match for {first_name} {last_name} with their likelihood scores.
        slots:
          first_name: query.first_name
          last_name: query.last_name
      - text: Identify candidate profiles for email {email}, ranked by likelihood.
        slots:
          email: query.email
      method: generated
      generated: '2026-10-01'
- target: $.paths['/person/bulk'].post
  update:
    x-apievangelist-phrasing:
      intent: Enrich many person profiles in one request
      effect: read
      questions:
      - Can I enrich a whole list of contacts at once instead of one call per person?
      - What's the way to batch person enrichment for a CRM export?
      instructions:
      - text: 'Bulk-enrich these people in a single request: {requests}.'
        slots:
          requests: requestBody.requests
      - text: Send my contact list {requests} as one batch person enrichment call.
        slots:
          requests: requestBody.requests
      method: generated
      generated: '2026-10-01'