# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Live Direct Marketing Online Contacts API
  version: 1.0.0
extends: openapi/live-direct-marketing-online-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: 24
- target: $.paths['/api/contacts/stats'].get
  update:
    x-apievangelist-phrasing:
      intent: Get contact statistics
      effect: read
      questions:
      - How many contacts do I have, and can I break the stats down for one list?
      - What contact statistics does Live Direct Marketing report for my workspace?
      instructions:
      - text: Show contact statistics for list {listId}.
        slots:
          listId: query.listId
      - text: Give me overall contact stats for my workspace.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/contacts/duplicates'].get
  update:
    x-apievangelist-phrasing:
      intent: Find duplicate contacts across the workspace
      effect: read
      questions:
      - Which contacts across my whole workspace look like duplicates?
      - Can I look for duplicate contacts by a specific field rather than email only?
      instructions:
      - text: Find duplicate contacts across the workspace by {field}.
        slots:
          field: query.field
      - text: Scan my workspace for duplicate contacts.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/contacts'].get
  update:
    x-apievangelist-phrasing:
      intent: List and search contacts
      effect: read
      questions:
      - Can I search my contacts and filter them by list, company or email validation status?
      - Which contacts have role-based or disposable email addresses?
      - Can I see contacts that are in the trash?
      instructions:
      - text: Search contacts for {search}, page {page} with {pageSize} per page.
        slots:
          search: query.search
          page: query.page
          pageSize: query.pageSize
      - text: List contacts in list {listId}.
        slots:
          listId: query.listId
      - text: Show contacts at company {companyId} sorted by {sortBy}.
        slots:
          companyId: query.companyId
          sortBy: query.sortBy
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/contacts'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a new contact
      effect: write
      questions:
      - How do I add a new person to my contacts?
      - Can I set a contact's position, department and company when creating them?
      instructions:
      - text: Create a contact named {firstName} {lastName}.
        slots:
          firstName: requestBody.firstName
          lastName: requestBody.lastName
      - text: Add a new contact {firstName} working as {position} at company {companyId}.
        slots:
          firstName: requestBody.firstName
          position: requestBody.position
          companyId: requestBody.companyId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/contacts/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a contact's details
      effect: read
      questions:
      - What details are stored for a particular contact?
      - Can I look up one contact record by its id?
      instructions:
      - text: Get contact {id}.
        slots:
          id: path.id
      - text: Show me the full record for contact {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/contacts/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Move a contact to the trash
      effect: destructive
      questions:
      - Can I delete a contact but still be able to restore it later?
      - What does soft-deleting a contact do?
      instructions:
      - text: Soft-delete contact {id}.
        slots:
          id: path.id
      - text: Move contact {id} to the trash.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/contacts/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a contact's details
      effect: write
      questions:
      - Can I change the name, job title or company on an existing contact?
      - What fields of a contact can I edit after it is created?
      instructions:
      - text: Update contact {id} to job title {position}.
        slots:
          id: path.id
          position: requestBody.position
      - text: Change contact {id}'s company to {companyId}.
        slots:
          id: path.id
          companyId: requestBody.companyId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/contacts/{id}/timeline'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a contact's activity timeline
      effect: read
      questions:
      - What has happened with a contact over time, event by event?
      - Can I page through the history of interactions for one person?
      instructions:
      - text: Show the timeline for contact {id}.
        slots:
          id: path.id
      - text: Get page {page} of contact {id}'s event history.
        slots:
          page: query.page
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/contacts/bulk'].post
  update:
    x-apievangelist-phrasing:
      intent: Run a bulk action on many contacts
      effect: write
      questions:
      - Can I add tags or move a whole filtered set of contacts to a list in one go?
      - Is there a way to update one field on hundreds of contacts at once?
      instructions:
      - text: Run bulk action {action} on contacts {contactIds}.
        slots:
          action: requestBody.action
          contactIds: requestBody.contactIds
      - text: Add all contacts matching {search} to list {listId}.
        slots:
          search: requestBody.search
          listId: requestBody.listId
      - text: Set {fieldName} to {fieldValue} on contacts {contactIds}.
        slots:
          fieldName: requestBody.fieldName
          fieldValue: requestBody.fieldValue
          contactIds: requestBody.contactIds
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/contacts/bulk/{jobId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check a bulk contact job's progress
      effect: read
      questions:
      - Has my bulk contact action finished yet?
      - What is the progress of a background bulk job on contacts?
      instructions:
      - text: Get the status of bulk contact job {jobId}.
        slots:
          jobId: path.jobId
      - text: Check progress on contact bulk job {jobId}.
        slots:
          jobId: path.jobId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/contacts/bulk/{jobId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Cancel a running bulk contact job
      effect: destructive
      questions:
      - Can I stop a bulk contact action that is still in progress?
      - What if I started a bulk delete on contacts by mistake; can I cancel it?
      instructions:
      - text: Cancel bulk contact job {jobId}.
        slots:
          jobId: path.jobId
      - text: Stop the in-progress contact bulk job {jobId}.
        slots:
          jobId: path.jobId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/contacts/export'].post
  update:
    x-apievangelist-phrasing:
      intent: Export contacts to a file
      effect: write
      questions:
      - Can I export my contacts to CSV or Excel, including custom fields?
      - Which contacts can I choose to export, a list or a search?
      instructions:
      - text: Export contacts in list {listId} as {format}.
        slots:
          listId: requestBody.listId
          format: requestBody.format
      - text: Export contacts with scope {scope} including custom fields {includeCustomFields}.
        slots:
          scope: requestBody.scope
          includeCustomFields: requestBody.includeCustomFields
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/contacts/import/preview'].post
  update:
    x-apievangelist-phrasing:
      intent: Preview a contacts import mapping
      effect: read
      questions:
      - Before importing a spreadsheet of contacts, can I see how the columns will be mapped?
      - Can I dry-run a contact import to check the field mapping?
      instructions:
      - text: Preview importing these contact rows {rows} with mapping {mapping}.
        slots:
          rows: requestBody.rows
          mapping: requestBody.mapping
      - text: Show how {rows} would map into contacts using {mapping}.
        slots:
          rows: requestBody.rows
          mapping: requestBody.mapping
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/contacts/import/start'].post
  update:
    x-apievangelist-phrasing:
      intent: Start a contacts import job
      effect: write
      questions:
      - How do I actually start importing a batch of contacts once the mapping looks right?
      - Can I pass import options when kicking off a contact import?
      instructions:
      - text: Start importing contact rows {rows} with mapping {mapping}.
        slots:
          rows: requestBody.rows
          mapping: requestBody.mapping
      - text: Import contacts {rows} using mapping {mapping} and options {options}.
        slots:
          rows: requestBody.rows
          mapping: requestBody.mapping
          options: requestBody.options
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/contacts/{id}/restore'].post
  update:
    x-apievangelist-phrasing:
      intent: Restore a contact from the trash
      effect: write
      questions:
      - Can I bring back a contact I soft-deleted?
      - Is there an undo for deleting a contact?
      instructions:
      - text: Restore contact {id} from the trash.
        slots:
          id: path.id
      - text: Undelete contact {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/contacts/{id}/purge'].delete
  update:
    x-apievangelist-phrasing:
      intent: Permanently delete a trashed contact
      effect: destructive
      questions:
      - Can I permanently erase a contact that is already in the trash?
      - Is purging a contact reversible?
      instructions:
      - text: Permanently purge trashed contact {id}.
        slots:
          id: path.id
      - text: Erase contact {id} for good from the trash.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/contacts/merge'].post
  update:
    x-apievangelist-phrasing:
      intent: Merge duplicate contacts into one
      effect: write
      questions:
      - Can I combine several duplicate contacts into a single record?
      - Which record survives when I merge contacts?
      instructions:
      - text: Merge contacts {mergeIds} into contact {keepId}.
        slots:
          mergeIds: requestBody.mergeIds
          keepId: requestBody.keepId
      - text: Keep contact {keepId} and fold {mergeIds} into it.
        slots:
          keepId: requestBody.keepId
          mergeIds: requestBody.mergeIds
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/contacts/{id}/dig'].post
  update:
    x-apievangelist-phrasing:
      intent: Run DIG email enrichment on a contact
      effect: write
      questions:
      - Can I re-check a contact's email domain for MX, SPF and DMARC on demand?
      - How do I trigger DIG enrichment manually for one person?
      instructions:
      - text: Run DIG email enrichment on contact {id}.
        slots:
          id: path.id
      - text: Trigger a DIG check for contact {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/contacts/{id}/duplicates'].get
  update:
    x-apievangelist-phrasing:
      intent: Check one contact for duplicates
      effect: read
      questions:
      - Does this specific contact have any duplicates in my workspace?
      - Can I find records that look like copies of one particular contact?
      instructions:
      - text: Check contact {id} for duplicates.
        slots:
          id: path.id
      - text: Find possible duplicates of contact {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/contacts/{id}/channels'].post
  update:
    x-apievangelist-phrasing:
      intent: Add an email or phone channel to a contact
      effect: write
      questions:
      - How do I attach an email address or phone number to a contact?
      - Can I mark a newly added channel as the contact's primary one?
      instructions:
      - text: Add a {type} channel {value} to contact {id}.
        slots:
          type: requestBody.type
          value: requestBody.value
          id: path.id
      - text: Attach {value} as the primary {type} for contact {id}.
        slots:
          value: requestBody.value
          type: requestBody.type
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/contacts/{contactId}/channels/{channelId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a channel from a contact
      effect: destructive
      questions:
      - Can I remove an old email address or phone number from a contact?
      - What happens when I delete one of a contact's channels?
      instructions:
      - text: Delete channel {channelId} from contact {contactId}.
        slots:
          channelId: path.channelId
          contactId: path.contactId
      - text: Remove contact {contactId}'s channel {channelId}.
        slots:
          contactId: path.contactId
          channelId: path.channelId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/contacts/{contactId}/channels/{channelId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a contact's email or phone channel
      effect: write
      questions:
      - Can I change the value or validation status of a contact's existing email channel?
      - Is it possible to switch which channel is primary for a contact?
      instructions:
      - text: Update channel {channelId} on contact {contactId} to {value}.
        slots:
          channelId: path.channelId
          contactId: path.contactId
          value: requestBody.value
      - text: Make channel {channelId} primary for contact {contactId}.
        slots:
          channelId: path.channelId
          contactId: path.contactId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/contacts/import/rollback/{batchId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Roll back a contact import batch
      effect: destructive
      questions:
      - I imported the wrong file; can I undo that whole contact import?
      - Can I remove every contact that came from one import batch?
      instructions:
      - text: Roll back contact import batch {batchId}.
        slots:
          batchId: path.batchId
      - text: Undo the contacts imported in batch {batchId}.
        slots:
          batchId: path.batchId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/contacts/duplicates/by-email'].get
  update:
    x-apievangelist-phrasing:
      intent: Find contacts sharing the same email
      effect: read
      questions:
      - Which contacts share the exact same email address?
      - Can I list duplicate contacts grouped by email?
      instructions:
      - text: Find contacts that share duplicate email addresses.
      - text: List contacts with the same email address.
      method: generated
      generated: '2026-10-01'