API Evangelist conversational phrasing for Common Room Contacts API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Common Room Contacts API
  version: 1.0.0
extends: openapi/common-room-contacts-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: 7
- target: $.paths['/source/{destinationSourceId}/user'].post
  update:
    x-apievangelist-phrasing:
      intent: Add or update a user in an API signal source
      effect: write
      questions:
      - How do I add a person from my own system into Common Room as a contact?
      - Can I update a user I already sent by reusing the same ID?
      - What profile details, like company, location or social handles, can I send for a user?
      instructions:
      - text: Add user {id} to source {destinationSourceId}.
        slots:
          id: requestBody.id
          destinationSourceId: path.destinationSourceId
      - text: Add user {id} named {fullName} with email {email} to source {destinationSourceId}.
        slots:
          id: requestBody.id
          fullName: requestBody.fullName
          email: requestBody.email
          destinationSourceId: path.destinationSourceId
      - text: Update user {id} in source {destinationSourceId} with title {titleAtCompany} at {companyName}.
        slots:
          id: requestBody.id
          destinationSourceId: path.destinationSourceId
          titleAtCompany: requestBody.titleAtCompany
          companyName: requestBody.companyName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/members/customFields'].get
  update:
    x-apievangelist-phrasing:
      intent: List contact custom fields for a room
      effect: read
      questions:
      - What custom fields are defined on contacts in our room?
      - Can I see the contact custom fields tied to one destination source?
      instructions:
      - text: List all contact custom fields in our room.
      - text: List the contact custom fields for source {destinationSourceId}.
        slots:
          destinationSourceId: query.destinationSourceId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/user/{email}'].get
  update:
    x-apievangelist-phrasing:
      intent: Look up a contact's profile by email
      effect: read
      questions:
      - How do I find a contact's full profile when all I have is their email address?
      - Can I retrieve someone's Common Room profile from a single email?
      instructions:
      - text: Get the contact profile for email {email}.
        slots:
          email: path.email
      - text: Pull up the person whose email address is {email}.
        slots:
          email: path.email
      method: generated
      generated: '2026-10-01'
- target: $.paths['/user/{email}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Request anonymization of a contact by email
      effect: destructive
      questions:
      - How do I remove a contact's personal data when they ask to be forgotten?
      - Does anonymizing a contact happen immediately or is it queued?
      instructions:
      - text: Anonymize the contact with email {email}.
        slots:
          email: path.email
      - text: Queue removal of all personal information for {email}.
        slots:
          email: path.email
      method: generated
      generated: '2026-10-01'
- target: $.paths['/members'].get
  update:
    x-apievangelist-phrasing:
      intent: Find a contact by email or social handle
      effect: read
      questions:
      - Can I find a contact by their GitHub, Twitter or LinkedIn handle?
      - Which lookup works when I have a social handle instead of a contact ID?
      instructions:
      - text: Find the contact with GitHub handle {github}.
        slots:
          github: query.github
      - text: Look up the member whose Twitter handle is {twitter} or LinkedIn is {linkedin}.
        slots:
          twitter: query.twitter
          linkedin: query.linkedin
      method: generated
      generated: '2026-10-01'
- target: $.paths['/contacts/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a contact by its ID
      effect: read
      questions:
      - How do I fetch one contact when I have its c_ ID?
      - Can I include columns like primary email or location when retrieving a contact by ID?
      instructions:
      - text: Get contact {id}.
        slots:
          id: path.id
      - text: Fetch contact {id} with columns {cols}.
        slots:
          id: path.id
          cols: query.cols
      method: generated
      generated: '2026-10-01'
- target: $.paths['/contacts'].get
  update:
    x-apievangelist-phrasing:
      intent: List contacts with filters and paging
      effect: read
      questions:
      - What's the way to page through every contact in our community?
      - Can I list only the contacts in a given segment or organization?
      - Is it possible to sort contacts by latest activity or a lead score?
      instructions:
      - text: List the contacts in segment {segmentId}.
        slots:
          segmentId: query.segmentId
      - text: List contacts at organization {organizationId} sorted by {sort}.
        slots:
          organizationId: query.organizationId
          sort: query.sort
      - text: Show {limit} contacts starting from cursor {cursor}.
        slots:
          limit: query.limit
          cursor: query.cursor
      method: generated
      generated: '2026-10-01'