# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Listrak Contact API
  version: 1.0.0
extends: openapi/listrak-contact-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: 10
- target: $.paths['/v1/List/{listId}/Contact'].get
  update:
    x-apievangelist-phrasing:
      intent: List email contacts on a list
      effect: read
      questions:
      - How do I pull every email subscriber on one of my lists?
      - Can I filter an email list's contacts by subscription state or date range?
      - Which email contacts joined a list between two dates?
      instructions:
      - text: List the email contacts on list {listId}.
        slots:
          listId: path.listId
      - text: Get email contacts on list {listId} with subscription state {subscriptionState}.
        slots:
          listId: path.listId
          subscriptionState: query.subscriptionState
      - text: Show email contacts added to list {listId} between {startDate} and {endDate}.
        slots:
          listId: path.listId
          startDate: query.startDate
          endDate: query.endDate
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/List/{listId}/Contact'].post
  update:
    x-apievangelist-phrasing:
      intent: Create or update an email contact
      effect: write
      questions:
      - How do I add or update an email subscriber on a list?
      - Can I send a double opt-in email when adding a new email contact?
      - Can I change a subscriber's email address to a new one?
      instructions:
      - text: Add or update email contact {emailAddress} on list {listId}.
        slots:
          emailAddress: requestBody.emailAddress
          listId: path.listId
      - text: Subscribe {emailAddress} to list {listId} and send a double opt-in confirmation.
        slots:
          emailAddress: requestBody.emailAddress
          listId: path.listId
      - text: Change the email of contact {emailAddress} on list {listId} to {newEmailAddress}.
        slots:
          emailAddress: requestBody.emailAddress
          listId: path.listId
          newEmailAddress: query.newEmailAddress
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/List/{listId}/Contact/{contactIdentifier}'].get
  update:
    x-apievangelist-phrasing:
      intent: Look up an email contact
      effect: read
      questions:
      - How do I find a single subscriber on an email list by their address?
      - Can I look up an email contact using their Listrak email key?
      instructions:
      - text: Get email contact {contactIdentifier} on list {listId}.
        slots:
          contactIdentifier: path.contactIdentifier
          listId: path.listId
      - text: Look up subscriber {contactIdentifier} on email list {listId} with profile fields {segmentationFieldIds}.
        slots:
          contactIdentifier: path.contactIdentifier
          listId: path.listId
          segmentationFieldIds: query.segmentationFieldIds
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/ShortCode/{senderCodeId}/PhoneList/{phoneListId}/Contact'].get
  update:
    x-apievangelist-phrasing:
      intent: List contacts on an SMS list
      effect: read
      questions:
      - How do I get all the phone contacts on an SMS list?
      - Can I see only the SMS contacts who opted out of a list?
      instructions:
      - text: List contacts on SMS list {phoneListId} for sender code {senderCodeId}.
        slots:
          phoneListId: path.phoneListId
          senderCodeId: path.senderCodeId
      - text: Show opted-out phone contacts on SMS list {phoneListId} under sender code {senderCodeId}.
        slots:
          phoneListId: path.phoneListId
          senderCodeId: path.senderCodeId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/ShortCode/{senderCodeId}/PhoneList/{phoneListId}/Contact'].post
  update:
    x-apievangelist-phrasing:
      intent: Create and subscribe an SMS contact
      effect: write
      questions:
      - How do I add a new phone number and subscribe it to an SMS list in one step?
      - Can I store a first name and birthday when creating a new SMS contact?
      instructions:
      - text: Create SMS contact {phoneNumber} and subscribe them to list {phoneListId} on sender code {senderCodeId}.
        slots:
          phoneNumber: requestBody.phoneNumber
          phoneListId: path.phoneListId
          senderCodeId: path.senderCodeId
      - text: Add new texting contact {phoneNumber} named {firstName} to SMS list {phoneListId} under sender code {senderCodeId}.
        slots:
          phoneNumber: requestBody.phoneNumber
          firstName: requestBody.firstName
          phoneListId: path.phoneListId
          senderCodeId: path.senderCodeId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/ShortCode/{senderCodeId}/Contact/{phoneNumber}'].get
  update:
    x-apievangelist-phrasing:
      intent: Look up an SMS contact by phone number
      effect: read
      questions:
      - How do I check an SMS contact's profile fields and opt-out status by phone number?
      - Is a given phone number opted out on my sender code?
      instructions:
      - text: Get the SMS contact for phone number {phoneNumber} on sender code {senderCodeId}.
        slots:
          phoneNumber: path.phoneNumber
          senderCodeId: path.senderCodeId
      - text: Check whether {phoneNumber} is opted out on sender code {senderCodeId}.
        slots:
          phoneNumber: path.phoneNumber
          senderCodeId: path.senderCodeId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/ShortCode/{senderCodeId}/Contact'].put
  update:
    x-apievangelist-phrasing:
      intent: Update an SMS contact's profile
      effect: write
      questions:
      - How do I update an existing texting contact's name or postal code?
      - Can I opt a phone contact out of a sender code through the API?
      instructions:
      - text: Update SMS contact {phoneNumber} on sender code {senderCodeId} with postal code {postalCode}.
        slots:
          phoneNumber: requestBody.phoneNumber
          senderCodeId: path.senderCodeId
          postalCode: requestBody.postalCode
      - text: Opt out phone contact {phoneNumber} on sender code {senderCodeId}.
        slots:
          phoneNumber: requestBody.phoneNumber
          senderCodeId: path.senderCodeId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/ShortCode/{senderCodeId}/OptOut'].get
  update:
    x-apievangelist-phrasing:
      intent: List opt-outs for an SMS sender code
      effect: read
      questions:
      - Who has opted out of texts across my whole sender code?
      - Can I see SMS opt-outs that happened within a date range?
      instructions:
      - text: List everyone opted out of sender code {senderCodeId}.
        slots:
          senderCodeId: path.senderCodeId
      - text: Show sender code {senderCodeId} opt-outs from {startDate} to {endDate}.
        slots:
          senderCodeId: path.senderCodeId
          startDate: query.startDate
          endDate: query.endDate
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/ShortCode/{senderCodeId}/ContactImport'].post
  update:
    x-apievangelist-phrasing:
      intent: Start an SMS contact update import
      effect: write
      questions:
      - How do I bulk update SMS contacts from a file on a sender code?
      - What is the largest file I can upload for an SMS contact import?
      instructions:
      - text: Import SMS contact file {fileName} into sender code {senderCodeId}.
        slots:
          fileName: requestBody.fileName
          senderCodeId: path.senderCodeId
      - text: Start a {importType} contact update import on sender code {senderCodeId} using file {fileName}.
        slots:
          importType: requestBody.importType
          senderCodeId: path.senderCodeId
          fileName: requestBody.fileName
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/ShortCode/{senderCodeId}/ContactImport/{importFileId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check an SMS contact import
      effect: read
      questions:
      - How do I check on an SMS contact import I already started?
      - Can I retrieve the details of a sender code contact import by its ID?
      instructions:
      - text: Get SMS contact import {importFileId} on sender code {senderCodeId}.
        slots:
          importFileId: path.importFileId
          senderCodeId: path.senderCodeId
      - text: Show me how contact import {importFileId} for sender code {senderCodeId} is going.
        slots:
          importFileId: path.importFileId
          senderCodeId: path.senderCodeId
      method: generated
      generated: '2026-09-26'