# 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-event-cloud-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 exist in my address book?
      - Can I filter contact groups or page through them by date?
      instructions:
      - text: List all 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:
      - Can I create a new group to organize contacts, like a distribution list?
      - What do I need to supply to make a contact group?
      instructions:
      - text: Create a contact group named {name} with ID {id}.
        slots:
          name: requestBody.name
          id: requestBody.id
      - text: Make a new contact group {name} (ID {id}) described as {description}.
        slots:
          name: requestBody.name
          id: requestBody.id
          description: requestBody.description
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contact-groups/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a contact group
      effect: read
      questions:
      - Can I see the details of one contact group, like its type and note?
      - What is the description of a particular contact group?
      instructions:
      - text: Get contact group {group}.
        slots:
          group: path.id
      - text: Show the settings of contact group {group}.
        slots:
          group: 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:
      - Can I rename an existing contact group?
      - How do I change the description or note on a contact group?
      instructions:
      - text: Rename contact group {group} to {name}.
        slots:
          group: path.id
          name: requestBody.name
      - text: Update the note on contact group {group} to {note}.
        slots:
          group: path.id
          note: requestBody.note
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contact-groups/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a contact group
      effect: destructive
      questions:
      - Can I delete a contact group I no longer use?
      - Is removing a whole contact group reversible?
      instructions:
      - text: Delete contact group {group}.
        slots:
          group: path.id
      - text: Remove the contact group {group} from the address book.
        slots:
          group: 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 given contact group?
      - Can I get just the contact IDs that are members of a group?
      instructions:
      - text: List the contact IDs in contact group {group}.
        slots:
          group: path.id
      - text: Show who is a member of contact group {group}.
        slots:
          group: 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 group
      effect: write
      questions:
      - Can I put a single contact into a contact group?
      - How do I add someone to one of my contact groups?
      instructions:
      - text: Add contact {contactId} to contact group {group}.
        slots:
          contactId: path.contactId
          group: path.id
      - text: Put contact {contactId} in group {group}.
        slots:
          contactId: path.contactId
          group: 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 group
      effect: destructive
      questions:
      - Can I take one contact out of a contact group without deleting them?
      - Does removing someone from a group keep them in the address book?
      instructions:
      - text: Remove contact {contactId} from contact group {group}.
        slots:
          contactId: path.contactId
          group: path.id
      - text: Take contact {contactId} out of group {group}.
        slots:
          contactId: path.contactId
          group: 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 list of 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 in the address book
      effect: read
      questions:
      - How do I page through all the contacts in my Cvent address book?
      - Can I include purged contacts when listing contacts?
      - Can I list contacts changed after a certain date?
      instructions:
      - text: List contacts matching filter {filter}.
        slots:
          filter: query.filter
      - text: 'List contacts modified after {after}, including purged ones: {includePurged}.'
        slots:
          after: query.after
          includePurged: query.includePurged
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contacts'].put
  update:
    x-apievangelist-phrasing:
      intent: Update several contacts at once
      effect: write
      questions:
      - Can I replace the details of many contacts in one bulk request?
      - What should I watch for when bulk-updating de-duplication fields on contacts?
      instructions:
      - text: Bulk update these contacts with the full records I provide.
      - text: Overwrite the listed contacts in one batch with their new values.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contacts'].post
  update:
    x-apievangelist-phrasing:
      intent: Create contacts in bulk
      effect: write
      questions:
      - Can I add a list of new contacts to the address book in one call?
      - Is there an upsert option when creating contacts so existing ones get updated?
      instructions:
      - text: Create these new contacts in the address book.
      - text: Create the contacts I provide 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 several contacts
      effect: write
      questions:
      - Can I change just a few fields on many contacts and leave the rest intact?
      - Which endpoint patches a batch of contacts without overwriting untouched values?
      instructions:
      - text: Patch only the provided fields on this batch of contacts.
      - text: Apply a partial update to multiple contacts, keeping all other values as they are.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contacts/filter'].post
  update:
    x-apievangelist-phrasing:
      intent: Search contacts with a body filter
      effect: read
      questions:
      - Can I search contacts with a filter longer than a URL allows?
      - Is there a POST search that returns the same data as listing contacts?
      instructions:
      - text: Search contacts using the body filter {filter}.
        slots:
          filter: requestBody.filter
      - text: Search contacts with filter {filter}, {limit} per page.
        slots:
          filter: requestBody.filter
          limit: query.limit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contacts/obfuscate/{obfuscateId}/status'].get
  update:
    x-apievangelist-phrasing:
      intent: Check a contact obfuscation status
      effect: read
      questions:
      - Has my request to anonymize a contact finished yet?
      - Where can I check the progress of a contact obfuscation?
      instructions:
      - text: Check the status of obfuscation {obfuscateId}.
        slots:
          obfuscateId: path.obfuscateId
      - text: Tell me whether obfuscation request {obfuscateId} has completed.
        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 the edit history of one contact 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:
      - Can I look up one contact's full record by ID?
      - Which sensitive fields like passport number need an extra scope to read on a contact?
      instructions:
      - text: Get contact {contact}.
        slots:
          contact: path.id
      - text: Show the address book record for contact {contact}.
        slots:
          contact: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contacts/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a contact's details
      effect: write
      questions:
      - Can I overwrite a single contact's record with new values?
      - What happens to fields I leave out when I fully update one contact?
      instructions:
      - text: Replace the record of contact {contact} with the values I provide.
        slots:
          contact: path.id
      - text: Fully update contact {contact} and set its parent contact to {parentId}.
        slots:
          contact: 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:
      - Can I delete a contact from the address book but keep them on events?
      - Does deleting a contact remove them from events they registered for?
      instructions:
      - text: Delete contact {contact} from the address book.
        slots:
          contact: path.id
      - text: Remove contact {contact} from my contacts.
        slots:
          contact: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contacts/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Change some fields on one contact
      effect: write
      questions:
      - Can I change just one contact's company or title without touching other fields?
      - How do I clear a single field on a contact by setting it to null?
      instructions:
      - text: Update the company of contact {contact} to {company}.
        slots:
          contact: path.id
          company: requestBody.company
      - text: Change contact {contact}'s job title to {title}.
        slots:
          contact: path.id
          title: requestBody.title
      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:
      - Can I record an answer to a custom field on a contact?
      - How do I update a single custom question value for one contact?
      instructions:
      - text: Set custom field {customFieldId} on contact {contact} to {value}.
        slots:
          customFieldId: path.customFieldId
          contact: path.id
          value: requestBody.value
      - text: Update contact {contact}'s answer to custom field {customFieldId} with {value}.
        slots:
          contact: path.id
          customFieldId: path.customFieldId
          value: requestBody.value
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contacts/{id}/merge'].post
  update:
    x-apievangelist-phrasing:
      intent: Merge duplicate contacts
      effect: destructive
      questions:
      - Can I combine duplicate contacts into one record?
      - How many contacts can be merged together at once?
      instructions:
      - text: Merge contacts {secondaryContacts} into contact {contact}.
        slots:
          secondaryContacts: requestBody.secondaryContacts
          contact: path.id
      - text: Merge duplicates {secondaryContacts} into primary contact {contact} using conflict resolution {conflictResolution}.
        slots:
          secondaryContacts: requestBody.secondaryContacts
          contact: 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:
      - Can I anonymize a contact to honor a privacy or data erasure request?
      - How do I start obfuscating a contact's personal information?
      instructions:
      - text: Obfuscate contact {contact}.
        slots:
          contact: path.id
      - text: Start anonymizing the personal data of contact {contact}.
        slots:
          contact: 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:
      - Can I give a contact a profile photo from an uploaded file?
      - Does assigning a new contact picture replace the existing one?
      instructions:
      - text: Set uploaded file {file} at {href} as the profile picture for contact {contact}.
        slots:
          file: requestBody.file
          href: requestBody.href
          contact: path.id
      - text: Replace contact {contact}'s photo with file {file} ({href}).
        slots:
          contact: path.id
          file: requestBody.file
          href: requestBody.href
      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:
      - Can I delete the photo on a contact's profile?
      - How do I clear a contact's profile image?
      instructions:
      - text: Delete the profile picture of contact {contact}.
        slots:
          contact: path.id
      - text: Remove contact {contact}'s profile photo.
        slots:
          contact: 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 other contacts are related to this person, like a guest or assistant?
      - Can I get the IDs of all contacts linked to one contact?
      instructions:
      - text: List contacts related to contact {contact}.
        slots:
          contact: path.id
      - text: Get the related contact IDs for {contact}.
        slots:
          contact: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contacts/{id}/related-contacts/{relatedContactId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Relate two contacts
      effect: write
      questions:
      - Can I link two contacts together as related?
      - How do I record that two people in my address book are connected?
      instructions:
      - text: Link contact {contact} with related contact {relatedContactId}.
        slots:
          contact: path.id
          relatedContactId: path.relatedContactId
      - text: Add a relationship between contacts {contact} and {relatedContactId}.
        slots:
          contact: 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:
      - Can I remove the link between two related contacts?
      - Does deleting a contact relationship delete either contact?
      instructions:
      - text: Remove the relationship between contact {contact} and {relatedContactId}.
        slots:
          contact: path.id
          relatedContactId: path.relatedContactId
      - text: Unlink related contact {relatedContactId} from contact {contact}.
        slots:
          relatedContactId: path.relatedContactId
          contact: path.id
      method: generated
      generated: '2026-09-26'