# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Birdeye Contact API
  version: 1.0.0
extends: openapi/birdeye-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: 11
- target: $.paths['/v1/customer-v2/external/saveCustomer'].post
  update:
    x-apievangelist-phrasing:
      intent: Create or update a contact
      effect: write
      questions:
      - Can I add a new contact or update an existing one in a single call?
      - Can I set a contact's SMS and email opt-in when saving them?
      instructions:
      - text: Save contact {firstName} {lastName} with email {email} to business {businessId}.
        slots:
          firstName: requestBody.firstName
          lastName: requestBody.lastName
          email: requestBody.email
          businessId: query.businessId
      - text: Update contact {id} in business {businessId} with phone {phone}.
        slots:
          id: requestBody.id
          businessId: query.businessId
          phone: requestBody.phone
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/customer-v2/external/getCustomer'].post
  update:
    x-apievangelist-phrasing:
      intent: Look up a contact
      effect: read
      questions:
      - Can I look up a contact by email or phone number?
      - Does fetching a contact also return their experience score?
      instructions:
      - text: Find the contact with email {email} in business {businessId}.
        slots:
          email: requestBody.email
          businessId: query.businessId
      - text: Get contact {id} from business {businessId}.
        slots:
          id: requestBody.id
          businessId: query.businessId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/customer-v2/external/deleteCustomer'].post
  update:
    x-apievangelist-phrasing:
      intent: Delete a contact from locations
      effect: destructive
      questions:
      - Can I delete a contact from one or more locations?
      - Is it possible to remove a contact from only some of my businesses?
      instructions:
      - text: Delete contact {id} from business {businessId}.
        slots:
          id: requestBody.id
          businessId: query.businessId
      - text: Remove contact {id} from locations {businessIds} under {businessId}.
        slots:
          id: requestBody.id
          businessIds: requestBody.businessIds
          businessId: query.businessId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/customer/checkin'].post
  update:
    x-apievangelist-phrasing:
      intent: Record a customer check-in
      effect: write
      questions:
      - Can I record a customer check-in at a location with their name and phone?
      - Can a check-in credit the employees who served the customer?
      instructions:
      - text: Check in customer {name} with phone {phone} at business {bid}.
        slots:
          name: requestBody.name
          phone: requestBody.phone
          bid: query.bid
      - text: Record a check-in for {emailId} at business {bid} served by {employees}.
        slots:
          emailId: requestBody.emailId
          bid: query.bid
          employees: requestBody.employees
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/customer/history/{customerId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a customer's activity history
      effect: read
      questions:
      - Can I see a customer's activity history for a date range?
      - Where can I find everything logged against one customer?
      instructions:
      - text: Get the activity log for customer {customerId} in business {businessId}.
        slots:
          customerId: path.customerId
          businessId: query.businessId
      - text: Show customer {customerId}'s history in {businessId} from {startDate} to {endDate}.
        slots:
          customerId: path.customerId
          businessId: query.businessId
          startDate: query.startDate
          endDate: query.endDate
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/customer/id/{customerId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an enterprise customer by ID
      effect: destructive
      questions:
      - Can I delete an enterprise customer record by its customer ID?
      - Is there a single call to erase a customer using only the customer ID?
      instructions:
      - text: Delete customer {customerId}.
        slots:
          customerId: path.customerId
      - text: Erase enterprise customer record {customerId}.
        slots:
          customerId: path.customerId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/customer-v2/change-permission'].post
  update:
    x-apievangelist-phrasing:
      intent: Subscribe or unsubscribe a customer
      effect: write
      questions:
      - Can I unsubscribe a customer from messages by email or phone?
      - Can I re-subscribe a customer who opted out?
      instructions:
      - text: Set permission {permission} for {email} on account {accountNumber}.
        slots:
          permission: requestBody.permission
          email: requestBody.email
          accountNumber: requestBody.accountNumber
      - text: Change messaging permission for phone {phone} on account {accountNumber} to {permission}.
        slots:
          phone: requestBody.phone
          accountNumber: requestBody.accountNumber
          permission: requestBody.permission
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/customer/list'].post
  update:
    x-apievangelist-phrasing:
      intent: List a business's contacts
      effect: read
      questions:
      - Can I page through all contacts of a business sorted my way?
      - Can I list contacts added within a date range?
      instructions:
      - text: List contacts for business {businessId}, page {page} of size {size}, sorted by {sortby}.
        slots:
          businessId: query.businessId
          page: query.page
          size: query.size
          sortby: query.sortby
      - text: Get contacts for {businessId} between {startDate} and {endDate}, page {page}, size {size}, sort {sortby}.
        slots:
          businessId: query.businessId
          startDate: requestBody.startDate
          endDate: requestBody.endDate
          page: query.page
          size: query.size
          sortby: query.sortby
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/contact/details'].post
  update:
    x-apievangelist-phrasing:
      intent: List customers or leads for a period
      effect: read
      questions:
      - Can I pull only leads rather than customers for a date range?
      - Can the customer or lead list include tags and custom field values?
      instructions:
      - text: List {contactType} records for business {businessId} from {startDateUtc} to {endDateUtc}, page {page}, size {size}.
        slots:
          contactType: requestBody.contactType
          businessId: requestBody.businessId
          startDateUtc: requestBody.startDateUtc
          endDateUtc: requestBody.endDateUtc
          page: requestBody.page
          size: requestBody.size
      - text: Get leads with their tags for business {businessId} between {startDateUtc} and {endDateUtc}.
        slots:
          businessId: requestBody.businessId
          startDateUtc: requestBody.startDateUtc
          endDateUtc: requestBody.endDateUtc
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/contactUs/{businessId}'].post
  update:
    x-apievangelist-phrasing:
      intent: Submit a contact-us request
      effect: write
      questions:
      - Can I submit a contact-us inquiry to a business on behalf of a customer?
      - Can a website form's message be sent into Birdeye as a contact request?
      instructions:
      - text: Send a contact-us request from {customer} to business {businessId}.
        slots:
          customer: requestBody.customer
          businessId: path.businessId
      - text: Submit contact-us comment {customerComment} from {customer} to {businessId}.
        slots:
          customerComment: requestBody.customerComment
          customer: requestBody.customer
          businessId: path.businessId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/contact/{businessId}/update-feed'].post
  update:
    x-apievangelist-phrasing:
      intent: Get a location's opt-out contact feed
      effect: read
      questions:
      - Which contacts unsubscribed from a business during a period?
      - Can I get a feed of subscription status changes for one location?
      instructions:
      - text: Get contacts with status {subscriptionStatus} for business {businessId} from {start} to {end}.
        slots:
          subscriptionStatus: requestBody.subscriptionStatus
          businessId: path.businessId
          start: requestBody.start
          end: requestBody.end
      - text: Show opt-out changes for {businessId} between {start} and {end}, status {subscriptionStatus}.
        slots:
          businessId: path.businessId
          start: requestBody.start
          end: requestBody.end
          subscriptionStatus: requestBody.subscriptionStatus
      method: generated
      generated: '2026-09-26'