# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Loops OpenAPI Spec Contacts API
  version: 1.0.0
extends: openapi/loops-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: 6
- target: $.paths['/v1/contacts/create'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a new contact
      effect: write
      questions:
      - How do I add a new subscriber to my audience?
      - Can I put a new contact on mailing lists when I create them?
      instructions:
      - text: Add contact {email} named {firstName} {lastName}.
        slots:
          email: requestBody.email
          firstName: requestBody.firstName
          lastName: requestBody.lastName
      - text: Create a new contact {email} with user ID {userId} in group {userGroup}.
        slots:
          email: requestBody.email
          userId: requestBody.userId
          userGroup: requestBody.userGroup
      - text: Create contact {email} and subscribe them to lists {mailingLists}.
        slots:
          email: requestBody.email
          mailingLists: requestBody.mailingLists
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/contacts/update'].put
  update:
    x-apievangelist-phrasing:
      intent: Update or upsert a contact
      effect: write
      questions:
      - How do I change an existing contact's name or properties?
      - Can I change a contact's email address if they have a user ID?
      - Will updating a contact create one if it doesn't exist yet?
      instructions:
      - text: Update the contact with user ID {userId} to email {email}.
        slots:
          userId: requestBody.userId
          email: requestBody.email
      - text: Unsubscribe existing contact {email} by setting subscribed to {subscribed}.
        slots:
          email: requestBody.email
          subscribed: requestBody.subscribed
      - text: Upsert contact {email} with first name {firstName}.
        slots:
          email: requestBody.email
          firstName: requestBody.firstName
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/contacts/find'].get
  update:
    x-apievangelist-phrasing:
      intent: Find a contact by email or user ID
      effect: read
      questions:
      - Is a given email address already a contact?
      - Can I look up a contact using my app's user ID?
      instructions:
      - text: Find the contact with email {email}.
        slots:
          email: query.email
      - text: Look up the contact whose user ID is {userId}.
        slots:
          userId: query.userId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/contacts/delete'].post
  update:
    x-apievangelist-phrasing:
      intent: Delete a contact
      effect: destructive
      questions:
      - How do I permanently remove someone from my audience?
      - Can I delete a contact using their user ID?
      instructions:
      - text: Delete the contact {email}.
        slots:
          email: requestBody.email
      - text: Remove contact with user ID {userId} from my audience.
        slots:
          userId: requestBody.userId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/contacts/suppression'].get
  update:
    x-apievangelist-phrasing:
      intent: Check a contact's suppression status
      effect: read
      questions:
      - Is this contact suppressed from receiving emails?
      - How many suppression removals do I have left?
      instructions:
      - text: Check whether {email} is suppressed.
        slots:
          email: query.email
      - text: Get suppression status for user ID {userId}.
        slots:
          userId: query.userId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/contacts/suppression'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a contact from the suppression list
      effect: destructive
      questions:
      - How do I unsuppress a contact so they can get emails again?
      - Can I take a user ID off the suppression list?
      instructions:
      - text: Remove {email} from the suppression list.
        slots:
          email: query.email
      - text: Unsuppress the contact with user ID {userId}.
        slots:
          userId: query.userId
      method: generated
      generated: '2026-09-26'