# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Ortto People API
  version: 1.0.0
extends: openapi/ortto-people-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: 4
- target: $.paths['/person/merge'].post
  update:
    x-apievangelist-phrasing:
      intent: Create or update contacts
      effect: write
      questions:
      - How do I sync contacts from my app into Ortto without creating duplicates?
      - Can I only update people who already exist and skip new ones?
      - What's the maximum number of people I can upsert in one call?
      - Can large contact imports be queued to process in the background?
      instructions:
      - text: Create or update these contacts {people}, matching existing records by {merge_by}.
        slots:
          people: requestBody.people
          merge_by: requestBody.merge_by
      - text: Update only existing contacts from {people} matched on {merge_by}, skipping anyone new ({skip_non_existing}).
        slots:
          people: requestBody.people
          merge_by: requestBody.merge_by
          skip_non_existing: requestBody.skip_non_existing
      - text: Queue an async upsert of {people} by {merge_by} with merge strategy {merge_strategy}.
        slots:
          people: requestBody.people
          merge_by: requestBody.merge_by
          merge_strategy: requestBody.merge_strategy
      method: generated
      generated: '2026-10-01'
- target: $.paths['/person/get'].post
  update:
    x-apievangelist-phrasing:
      intent: Search contacts with a filter
      effect: read
      questions:
      - How can I find all contacts matching a condition, like a certain city or tag?
      - Can I page through my contact list and sort it by a field?
      - Which contact fields can I choose to return when searching people?
      instructions:
      - text: Find contacts matching filter {filter} and return fields {fields}.
        slots:
          filter: requestBody.filter
          fields: requestBody.fields
      - text: List {limit} contacts starting at offset {offset}, sorted by {sort_by_field_id} {sort_order}.
        slots:
          limit: requestBody.limit
          offset: requestBody.offset
          sort_by_field_id: requestBody.sort_by_field_id
          sort_order: requestBody.sort_order
      method: generated
      generated: '2026-10-01'
- target: $.paths['/person/get-by-ids'].post
  update:
    x-apievangelist-phrasing:
      intent: Look up contacts by their contact IDs
      effect: read
      questions:
      - I already have Ortto contact IDs; how do I fetch those exact people?
      - Can I retrieve several known contact records at once and pick which fields come back?
      instructions:
      - text: Fetch the contacts with IDs {contact_ids}.
        slots:
          contact_ids: requestBody.contact_ids
      - text: Get fields {fields} for contact IDs {contact_ids}.
        slots:
          fields: requestBody.fields
          contact_ids: requestBody.contact_ids
      method: generated
      generated: '2026-10-01'
- target: $.paths['/person/delete'].post
  update:
    x-apievangelist-phrasing:
      intent: Delete contacts
      effect: destructive
      questions:
      - How do I permanently remove contacts from my Ortto account?
      - Can I delete several people in a single request?
      instructions:
      - text: 'Delete these contacts: {people}.'
        slots:
          people: requestBody.people
      - text: Permanently remove person records {people} from the customer database.
        slots:
          people: requestBody.people
      method: generated
      generated: '2026-10-01'