# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Cvent REST Contacts API
  version: 1.0.0
extends: openapi/cvent-contacts-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: 28
- target: $.paths['/contact-groups'].get
  update:
    x-apievangelist-phrasing:
      intent: List contact groups
      effect: read
      questions:
      - What contact groups do I have in my Cvent address book?
      - Can I list only contact groups created after a certain date?
      instructions:
      - text: List all my contact groups.
      - text: List contact groups matching {filter}.
        slots:
          filter: query.filter
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contact-groups'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a contact group
      effect: write
      questions:
      - How do I set up a new group to organize contacts, like a VIP list?
      - Can I give a contact group a short description and a note when creating it?
      instructions:
      - text: Create a contact group named {name} with ID {id}.
        slots:
          name: requestBody.name
          id: requestBody.id
      - text: Create contact group {name} described as {shortDescription}, using ID {id}.
        slots:
          name: requestBody.name
          shortDescription: requestBody.shortDescription
          id: requestBody.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contact-groups/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a contact group
      effect: read
      questions:
      - How do I look up one contact group's details?
      - What type and description does a given contact group have?
      instructions:
      - text: Get contact group {id}.
        slots:
          id: path.id
      - text: Show the details of contact group {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contact-groups/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a contact group
      effect: write
      questions:
      - How do I rename an existing contact group?
      - Can I change the description or note on a contact group?
      instructions:
      - text: Rename contact group {id} to {name}.
        slots:
          id: path.id
          name: requestBody.name
      - text: Update the description of contact group {id} to {description}.
        slots:
          id: path.id
          description: requestBody.description
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contact-groups/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a contact group
      effect: destructive
      questions:
      - How do I delete a contact group I no longer use?
      - Does deleting a contact group get rid of the group itself permanently?
      instructions:
      - text: Delete contact group {id}.
        slots:
          id: path.id
      - text: Remove the contact group {id} from my account.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contact-groups/{id}/contacts'].get
  update:
    x-apievangelist-phrasing:
      intent: List contact IDs in a group
      effect: read
      questions:
      - Which contacts belong to a particular contact group?
      - Can I page through the member IDs of a contact group?
      instructions:
      - text: List the contact IDs in contact group {id}.
        slots:
          id: path.id
      - text: Show who is a member of contact group {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contact-groups/{id}/contacts/{contactId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Add a contact to a contact group
      effect: write
      questions:
      - How do I put a contact into one of my contact groups?
      - Can I add a single person to a group without re-saving the whole group?
      instructions:
      - text: Add contact {contactId} to contact group {id}.
        slots:
          contactId: path.contactId
          id: path.id
      - text: Put contact {contactId} in group {id}.
        slots:
          contactId: path.contactId
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contact-groups/{id}/contacts/{contactId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a contact from a contact group
      effect: destructive
      questions:
      - How do I take someone out of a contact group without deleting their contact record?
      - Can I remove just one member from a contact group?
      instructions:
      - text: Remove contact {contactId} from contact group {id}.
        slots:
          contactId: path.contactId
          id: path.id
      - text: Take contact {contactId} out of group {id}.
        slots:
          contactId: path.contactId
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contact-types'].get
  update:
    x-apievangelist-phrasing:
      intent: List contact types
      effect: read
      questions:
      - What contact types are defined in my account?
      - Can I filter the available contact types?
      instructions:
      - text: List all contact types.
      - text: List contact types matching {filter}.
        slots:
          filter: query.filter
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contacts'].get
  update:
    x-apievangelist-phrasing:
      intent: List contacts
      effect: read
      questions:
      - How do I pull all the contacts in my address book?
      - Can I include purged contacts when listing contacts?
      - Which contacts were changed since last week?
      instructions:
      - text: List all my contacts.
      - text: List contacts updated after {after}.
        slots:
          after: query.after
      - text: 'List contacts matching the query filter {filter}, including purged ones: {includePurged}.'
        slots:
          filter: query.filter
          includePurged: query.includePurged
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contacts'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace fields on many contacts at once
      effect: write
      questions:
      - How do I update a batch of contacts in one request?
      - Do de-duplication fields like email need to stay unique when bulk-updating contacts?
      instructions:
      - text: Bulk update the contacts in this list with a full replacement of their values.
      - text: Overwrite these contacts' records in one batch update.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contacts'].post
  update:
    x-apievangelist-phrasing:
      intent: Create contacts in bulk
      effect: write
      questions:
      - How do I import a list of new contacts into my address book?
      - Can creating contacts update existing ones instead of failing on duplicates?
      instructions:
      - text: Create these new contacts in my address book.
      - text: Create these contacts with upsert set to {upsert}.
        slots:
          upsert: query.upsert
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contacts'].patch
  update:
    x-apievangelist-phrasing:
      intent: Partially update many contacts
      effect: write
      questions:
      - How do I change just a couple of fields on many contacts while keeping everything else?
      - Can I bulk-patch contacts without wiping fields I don't send?
      instructions:
      - text: Patch only the supplied fields on this batch of contacts.
      - text: Apply a partial update to these contacts, leaving other values intact.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contacts/filter'].post
  update:
    x-apievangelist-phrasing:
      intent: Search contacts with a long body filter
      effect: read
      questions:
      - My contact filter is too long for the URL — can I send it in the body?
      - Can I search contacts with a complex filter and a date range?
      instructions:
      - text: Search contacts using the body filter {filter}.
        slots:
          filter: requestBody.filter
      - text: Find contacts matching body filter {filter} updated before {before}.
        slots:
          filter: requestBody.filter
          before: query.before
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contacts/obfuscate/{obfuscateId}/status'].get
  update:
    x-apievangelist-phrasing:
      intent: Check a contact obfuscation's status
      effect: read
      questions:
      - How do I know whether a contact's data has finished being obfuscated?
      - Can I check the progress of a GDPR-style contact obfuscation request?
      instructions:
      - text: Check the status of obfuscation request {obfuscateId}.
        slots:
          obfuscateId: path.obfuscateId
      - text: Tell me whether obfuscation {obfuscateId} has finished.
        slots:
          obfuscateId: path.obfuscateId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contacts/{contactId}/history'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a contact's change history
      effect: read
      questions:
      - Who changed a contact's record and when?
      - Can I see a contact's edit history within a date range?
      instructions:
      - text: Show the change history for contact {contactId}.
        slots:
          contactId: path.contactId
      - text: List changes to contact {contactId} made after {after}.
        slots:
          contactId: path.contactId
          after: query.after
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contacts/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a contact
      effect: read
      questions:
      - How do I look up one contact's full record?
      - Are sensitive fields like passport number returned when I read a contact?
      instructions:
      - text: Get contact {id}.
        slots:
          id: path.id
      - text: Show the full record for contact {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contacts/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a single contact's record
      effect: write
      questions:
      - How do I overwrite a contact's details with new values?
      - What scope do I need to write secure fields like date of birth on a contact?
      instructions:
      - text: Replace the record for contact {id} with these values.
        slots:
          id: path.id
      - text: Fully update contact {id} and set its parent contact to {parentId}.
        slots:
          id: path.id
          parentId: requestBody.parentId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contacts/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a contact from the address book
      effect: destructive
      questions:
      - How do I delete a contact from my address book?
      - Does deleting a contact also remove them from events they're registered for?
      instructions:
      - text: Delete contact {id} from the address book.
        slots:
          id: path.id
      - text: Remove contact {id}, leaving their event registrations alone.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contacts/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Partially update a contact
      effect: write
      questions:
      - How do I change just a contact's company or title without touching other fields?
      - Can I clear a single field on a contact by setting it to null?
      instructions:
      - text: Change contact {id}'s company to {company}.
        slots:
          id: path.id
          company: requestBody.company
      - text: Set the job title of contact {id} to {title}.
        slots:
          id: path.id
          title: requestBody.title
      - text: Update the home phone for contact {id} to {homePhone}.
        slots:
          id: path.id
          homePhone: requestBody.homePhone
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contacts/{id}/custom-fields/{customFieldId}/answers'].put
  update:
    x-apievangelist-phrasing:
      intent: Set a contact's custom field answer
      effect: write
      questions:
      - How do I fill in a custom question answer on a contact's profile?
      - Can I update one custom field value for a single contact?
      instructions:
      - text: Set custom field {customFieldId} on contact {id} to {value}.
        slots:
          customFieldId: path.customFieldId
          id: path.id
          value: requestBody.value
      - text: Update contact {id}'s answer for custom field {customFieldId}.
        slots:
          id: path.id
          customFieldId: path.customFieldId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contacts/{id}/merge'].post
  update:
    x-apievangelist-phrasing:
      intent: Merge duplicate contacts
      effect: write
      questions:
      - How do I merge duplicate contacts into one record?
      - How many contacts can be merged together at once?
      - Can I choose which fields to keep when merging contacts?
      instructions:
      - text: Merge contacts {secondaryContacts} into contact {id}.
        slots:
          secondaryContacts: requestBody.secondaryContacts
          id: path.id
      - text: Merge duplicates {secondaryContacts} into {id}, resolving conflicts with {conflictResolution}.
        slots:
          secondaryContacts: requestBody.secondaryContacts
          id: path.id
          conflictResolution: requestBody.conflictResolution
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contacts/{id}/obfuscate'].post
  update:
    x-apievangelist-phrasing:
      intent: Obfuscate a contact's personal data
      effect: destructive
      questions:
      - How do I permanently scrub a contact's personal data for a privacy request?
      - Is contact obfuscation reversible once it succeeds?
      instructions:
      - text: Obfuscate contact {id}.
        slots:
          id: path.id
      - text: Start irreversible obfuscation of all data for contact {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contacts/{id}/profile-images'].put
  update:
    x-apievangelist-phrasing:
      intent: Set a contact's profile picture
      effect: write
      questions:
      - How do I add a profile photo to a contact?
      - Does assigning a new profile picture replace the contact's existing one?
      instructions:
      - text: Set uploaded file {file} as the profile picture for contact {id}.
        slots:
          file: requestBody.file
          id: path.id
      - text: Assign profile image {file} at {href} to contact {id}.
        slots:
          file: requestBody.file
          href: requestBody.href
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contacts/{id}/profile-images'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a contact's profile picture
      effect: destructive
      questions:
      - How do I remove the photo from a contact's profile?
      - Can I clear a contact's profile picture without deleting the contact?
      instructions:
      - text: Delete the profile picture of contact {id}.
        slots:
          id: path.id
      - text: Remove contact {id}'s profile photo.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contacts/{id}/related-contacts'].get
  update:
    x-apievangelist-phrasing:
      intent: List a contact's related contacts
      effect: read
      questions:
      - Which contacts are linked to this contact, like a spouse or assistant?
      - Can I see all related contact IDs for one person?
      instructions:
      - text: List contacts related to contact {id}.
        slots:
          id: path.id
      - text: Show the related contact IDs for {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contacts/{id}/related-contacts/{relatedContactId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Link two contacts as related
      effect: write
      questions:
      - How do I record that two contacts are related to each other?
      - Can I connect a contact to their guest or colleague in the address book?
      instructions:
      - text: Link contact {id} with related contact {relatedContactId}.
        slots:
          id: path.id
          relatedContactId: path.relatedContactId
      - text: Add a relationship between contacts {id} and {relatedContactId}.
        slots:
          id: path.id
          relatedContactId: path.relatedContactId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contacts/{id}/related-contacts/{relatedContactId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Unlink two related contacts
      effect: destructive
      questions:
      - How do I remove the relationship between two contacts?
      - Can I unlink related contacts without deleting either one?
      instructions:
      - text: Remove the relationship between contact {id} and {relatedContactId}.
        slots:
          id: path.id
          relatedContactId: path.relatedContactId
      - text: Unlink related contact {relatedContactId} from contact {id}.
        slots:
          relatedContactId: path.relatedContactId
          id: path.id
      method: generated
      generated: '2026-09-26'