# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Contacts API
  version: 1.0.0
extends: openapi/omnisend-contacts-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-02'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 7
- target: $.paths['/contacts'].get
  update:
    x-apievangelist-phrasing:
      intent: List contacts
      effect: read
      questions:
      - Which contacts carry a specific tag?
      - Can I look up contacts by phone number?
      - What subscribers belong to a given segment?
      - Which contacts changed since a certain time?
      instructions:
      - text: List contacts tagged {tag}.
        slots:
          tag: query.tag
      - text: Find contacts with email {email}.
        slots:
          email: query.email
      - text: List contacts in segment {segmentID}.
        slots:
          segmentID: query.segmentID
      - text: List contacts updated since {updatedAtFrom}.
        slots:
          updatedAtFrom: query.updatedAtFrom
      method: generated
      generated: '2026-10-02'
- target: $.paths['/contacts'].post
  update:
    x-apievangelist-phrasing:
      intent: Create or upsert a contact
      effect: write
      questions:
      - How do I add a new subscriber, or update them if the email already exists?
      - Can I set custom properties and tags when creating a contact?
      instructions:
      - text: Create a contact with identifiers {identifiers}, first name {firstName} and last name {lastName}.
        slots:
          identifiers: requestBody.identifiers
          firstName: requestBody.firstName
          lastName: requestBody.lastName
      - text: Add a new contact with identifiers {identifiers} and tags {tags}.
        slots:
          identifiers: requestBody.identifiers
          tags: requestBody.tags
      method: generated
      generated: '2026-10-02'
- target: $.paths['/contacts'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a contact by email address
      effect: write
      questions:
      - Can I update a contact using only their email address?
      - What fields can I change on a contact when all I know is their email?
      instructions:
      - text: Update the contact with email {email} to first name {firstName}.
        slots:
          email: query.email
          firstName: requestBody.firstName
      - text: Change the city of the contact whose email is {email} to {city}.
        slots:
          email: query.email
          city: requestBody.city
      method: generated
      generated: '2026-10-02'
- target: $.paths['/contacts/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one contact by ID
      effect: read
      questions:
      - Can I fetch one contact's full profile by its contact ID?
      - What details are stored on the contact record with a given ID?
      instructions:
      - text: Show contact {id}.
        slots:
          id: path.id
      - text: Get the profile of the contact with ID {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-02'
- target: $.paths['/contacts/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a contact by ID
      effect: write
      questions:
      - How do I update a contact's details when I have their contact ID?
      - Can I change a contact's birthdate or gender by contact ID?
      instructions:
      - text: Update contact {id} with last name {lastName}.
        slots:
          id: path.id
          lastName: requestBody.lastName
      - text: Set custom properties {customProperties} on contact {id}.
        slots:
          customProperties: requestBody.customProperties
          id: path.id
      method: generated
      generated: '2026-10-02'
- target: $.paths['/contacts/tags'].post
  update:
    x-apievangelist-phrasing:
      intent: Add tags to many contacts
      effect: write
      questions:
      - Can I add a tag to every contact in a segment at once?
      - Is there a way to bulk tag a list of email addresses or phone numbers?
      instructions:
      - text: Add tags {tags} to the contacts with emails {emails}.
        slots:
          tags: requestBody.tags
          emails: requestBody.emails
      - text: Tag everyone in segment {segmentID} with {tags}.
        slots:
          segmentID: requestBody.segmentID
          tags: requestBody.tags
      method: generated
      generated: '2026-10-02'
- target: $.paths['/contacts/tags'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove tags from many contacts
      effect: destructive
      questions:
      - Can I remove a tag from many contacts in one call?
      - How can I strip tags from all members of a segment?
      instructions:
      - text: Remove tags {tags} from contacts {contactIDs}.
        slots:
          tags: requestBody.tags
          contactIDs: requestBody.contactIDs
      - text: Take tags {tags} off every contact in segment {segmentID}.
        slots:
          tags: requestBody.tags
          segmentID: requestBody.segmentID
      method: generated
      generated: '2026-10-02'