# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Contact Management Contacts API
  version: 1.0.0
extends: openapi/brevo-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: 29
- target: $.paths['/contacts/attributes/{attributeCategory}/{attributeName}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a contact attribute
      effect: write
      questions:
      - Can I change the dropdown values of a category attribute that already exists on my contacts?
      - What can be edited on a calculated or global contact attribute after it is created?
      instructions:
      - text: Update the enumeration values of the {name} attribute in the {category} category.
        slots:
          name: path.attributeName
          category: path.attributeCategory
      - text: Change the formula of the calculated contact attribute {name} to {value}.
        slots:
          name: path.attributeName
          value: requestBody.value
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contacts/attributes/{attributeCategory}/{attributeName}'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a new contact attribute
      effect: write
      questions:
      - How do I add a custom field like a birthday or loyalty tier to my Brevo contacts?
      - Which attribute types can I choose when defining a brand-new contact field?
      instructions:
      - text: Create a new {type} contact attribute called {name} in the {category} category.
        slots:
          type: requestBody.type
          name: path.attributeName
          category: path.attributeCategory
      - text: Add a new calculated contact field {name} with formula {value}.
        slots:
          name: path.attributeName
          value: requestBody.value
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contacts/attributes/{attributeCategory}/{attributeName}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a contact attribute
      effect: destructive
      questions:
      - Can I permanently remove a contact field I no longer use?
      - What happens if I try to delete an attribute that isn't in the category I name?
      instructions:
      - text: Delete the contact attribute {name} from the {category} category.
        slots:
          name: path.attributeName
          category: path.attributeCategory
      - text: Permanently remove the {name} field from my contact attributes in {category}.
        slots:
          name: path.attributeName
          category: path.attributeCategory
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contacts/attributes'].get
  update:
    x-apievangelist-phrasing:
      intent: List all contact attributes
      effect: read
      questions:
      - What custom fields are defined on the contacts in my account?
      - Which contact attributes are calculated versus transactional or global?
      instructions:
      - text: List every contact attribute in my account grouped by category.
      - text: Show all the contact fields and their types for the account with API key {api_key}.
        slots:
          api_key: header.api-key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contacts/attributes/{attributeType}/{multipleChoiceAttribute}/{multipleChoiceAttributeOption}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove an option from a multiple-choice attribute
      effect: destructive
      questions:
      - Can I delete one choice from a multiple-choice contact field without deleting the whole field?
      - What is required to drop a single option from a multi-select contact attribute?
      instructions:
      - text: Remove the option {option} from the multiple-choice attribute {attribute}.
        slots:
          option: path.multipleChoiceAttributeOption
          attribute: path.multipleChoiceAttribute
      - text: Delete choice {option} from {attribute} of attribute type {type}.
        slots:
          option: path.multipleChoiceAttributeOption
          attribute: path.multipleChoiceAttribute
          type: path.attributeType
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contacts/lists'].get
  update:
    x-apievangelist-phrasing:
      intent: List all contact lists
      effect: read
      questions:
      - What contact lists do I have in my Brevo account?
      - Can I page through my contact lists sorted oldest first?
      instructions:
      - text: List all my contact lists.
      - text: Show {limit} contact lists starting at offset {offset}.
        slots:
          limit: query.limit
          offset: query.offset
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contacts/lists'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a contact list
      effect: write
      questions:
      - How do I create a new mailing list inside one of my folders?
      - Does a newly created contact list start out empty?
      instructions:
      - text: Create a contact list named {name} in folder {folderId}.
        slots:
          name: requestBody.name
          folderId: requestBody.folderId
      - text: Make a new empty list called {name} under folder {folderId}.
        slots:
          name: requestBody.name
          folderId: requestBody.folderId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contacts/lists/{listId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a contact list's details
      effect: read
      questions:
      - How many subscribers does a specific list have and when was it created?
      - Can I see campaign statistics for one list over a date range?
      instructions:
      - text: Show the details of contact list {listId}.
        slots:
          listId: path.listId
      - text: Get campaign stats for list {listId} between {startDate} and {endDate}.
        slots:
          listId: path.listId
          startDate: query.startDate
          endDate: query.endDate
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contacts/lists/{listId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Rename or move a contact list
      effect: write
      questions:
      - Can I rename an existing contact list?
      - Is it possible to move a list into a different folder?
      instructions:
      - text: Rename contact list {listId} to {name}.
        slots:
          listId: path.listId
          name: requestBody.name
      - text: Move list {listId} into folder {folderId}.
        slots:
          listId: path.listId
          folderId: requestBody.folderId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contacts/lists/{listId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a contact list
      effect: destructive
      questions:
      - If I delete a list, are the contacts in it deleted too?
      - Can I permanently remove a contact list I no longer need?
      instructions:
      - text: Delete contact list {listId}.
        slots:
          listId: path.listId
      - text: Permanently remove list {listId} but keep its contacts.
        slots:
          listId: path.listId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contacts/lists/{listId}/contacts'].get
  update:
    x-apievangelist-phrasing:
      intent: List the contacts in a list
      effect: read
      questions:
      - Who is subscribed to a particular contact list?
      - Can I get only the list members modified since a certain date?
      - What is the maximum number of list members returned per page?
      instructions:
      - text: Show the contacts in list {listId}.
        slots:
          listId: path.listId
      - text: List members of list {listId} modified since {modifiedSince}.
        slots:
          listId: path.listId
          modifiedSince: query.modifiedSince
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contacts/lists/{listId}/contacts/remove'].post
  update:
    x-apievangelist-phrasing:
      intent: Remove contacts from a list
      effect: write
      questions:
      - How do I unsubscribe existing contacts from one list without deleting them?
      - Can I take contacts off a list but keep them in my account?
      instructions:
      - text: Remove contacts from list {listId}.
        slots:
          listId: path.listId
      - text: Take the selected contacts off list {listId}.
        slots:
          listId: path.listId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contacts/lists/{listId}/contacts/add'].post
  update:
    x-apievangelist-phrasing:
      intent: Add existing contacts to a list
      effect: write
      questions:
      - Can I add contacts who already exist in my account to another list?
      - What's the way to put existing contacts into a list in bulk?
      instructions:
      - text: Add existing contacts to list {listId}.
        slots:
          listId: path.listId
      - text: Put the selected contacts into list {listId}.
        slots:
          listId: path.listId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contacts/folders'].get
  update:
    x-apievangelist-phrasing:
      intent: List all contact folders
      effect: read
      questions:
      - What folders do I use to organize my contact lists?
      - Can I page through all my list folders?
      instructions:
      - text: List all my contact folders.
      - text: Show {limit} folders starting at offset {offset}.
        slots:
          limit: query.limit
          offset: query.offset
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contacts/folders'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a folder for contact lists
      effect: write
      questions:
      - How can I create a folder to group related contact lists?
      - Is a name the only thing needed to create a list folder?
      instructions:
      - text: Create a contact folder named {name}.
        slots:
          name: requestBody.name
      - text: Make a new folder called {name} to hold my lists.
        slots:
          name: requestBody.name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contacts/folders/{folderId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a folder's details
      effect: read
      questions:
      - What are the details of one of my contact folders?
      - Can I look up a single folder by its ID?
      instructions:
      - text: Show the details of folder {folderId}.
        slots:
          folderId: path.folderId
      - text: Get folder {folderId}.
        slots:
          folderId: path.folderId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contacts/folders/{folderId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Rename a contact folder
      effect: write
      questions:
      - Can I rename one of my contact folders?
      - What error do I get when renaming a folder that doesn't exist?
      instructions:
      - text: Rename folder {folderId} to {name}.
        slots:
          folderId: path.folderId
          name: requestBody.name
      - text: Change the name of contact folder {folderId} to {name}.
        slots:
          folderId: path.folderId
          name: requestBody.name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contacts/folders/{folderId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a folder and all its lists
      effect: destructive
      questions:
      - Does deleting a folder also delete the lists inside it?
      - Can a deleted contact folder be recovered?
      instructions:
      - text: Delete folder {folderId} along with all its lists.
        slots:
          folderId: path.folderId
      - text: Permanently remove contact folder {folderId}.
        slots:
          folderId: path.folderId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contacts/folders/{folderId}/lists'].get
  update:
    x-apievangelist-phrasing:
      intent: List the lists inside a folder
      effect: read
      questions:
      - Which contact lists live inside a given folder?
      - Can I page through the lists in one folder?
      instructions:
      - text: Show the lists in folder {folderId}.
        slots:
          folderId: path.folderId
      - text: List {limit} lists from folder {folderId}.
        slots:
          limit: query.limit
          folderId: path.folderId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contacts'].get
  update:
    x-apievangelist-phrasing:
      intent: List and filter contacts
      effect: read
      questions:
      - How do I pull all contacts from my Brevo account?
      - Can I list only contacts created since a certain date or in a specific segment?
      - What is the maximum number of contacts per page when listing them?
      instructions:
      - text: List all my contacts.
      - text: List contacts created since {createdSince}.
        slots:
          createdSince: query.createdSince
      - text: Show the contacts in segment {segmentId}.
        slots:
          segmentId: query.segmentId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contacts'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a contact
      effect: write
      questions:
      - Can I add a new contact with an email and assign them to lists at the same time?
      - What phone format is accepted for the SMS attribute when creating a contact?
      - Is it possible to update the contact instead if the email already exists?
      instructions:
      - text: Create a contact with email {email}.
        slots:
          email: requestBody.email
      - text: Add {email} as a new contact and put them in lists {listIds}.
        slots:
          email: requestBody.email
          listIds: requestBody.listIds
      - text: Create contact {email} with external ID {ext_id}.
        slots:
          email: requestBody.email
          ext_id: requestBody.ext_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contacts/doubleOptinConfirmation'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a contact through double opt-in
      effect: write
      questions:
      - How do I send a double opt-in confirmation email before adding someone to my list?
      - Where does the subscriber land after confirming a double opt-in?
      instructions:
      - text: Send a double opt-in email to {email} using template {templateId} and add them to lists {includeListIds} once confirmed.
        slots:
          email: requestBody.email
          templateId: requestBody.templateId
          includeListIds: requestBody.includeListIds
      - text: Start DOI for {email} with template {templateId}, lists {includeListIds}, redirecting to {redirectionUrl}.
        slots:
          email: requestBody.email
          templateId: requestBody.templateId
          includeListIds: requestBody.includeListIds
          redirectionUrl: requestBody.redirectionUrl
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contacts/{identifier}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a contact's details
      effect: read
      questions:
      - Can I look up a single contact by email, phone number or external ID?
      - What attributes and list memberships does a particular contact have?
      instructions:
      - text: Show the details of contact {identifier}.
        slots:
          identifier: path.identifier
      - text: Look up contact {identifier} by {identifierType}.
        slots:
          identifier: path.identifier
          identifierType: query.identifierType
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contacts/{identifier}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a contact
      effect: write
      questions:
      - How do I change the attributes of an existing contact?
      - Can I blocklist a contact from emails or remove them from certain lists when editing them?
      instructions:
      - text: Update contact {identifier} with attributes {attributes}.
        slots:
          identifier: path.identifier
          attributes: requestBody.attributes
      - text: Unlink contact {identifier} from lists {unlinkListIds}.
        slots:
          identifier: path.identifier
          unlinkListIds: requestBody.unlinkListIds
      - text: Blocklist contact {identifier} from email.
        slots:
          identifier: path.identifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contacts/{identifier}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a contact
      effect: destructive
      questions:
      - Can I delete a contact using their email or external ID?
      - Is deleting a contact from my account permanent?
      instructions:
      - text: Delete contact {identifier}.
        slots:
          identifier: path.identifier
      - text: Delete the contact identified by {identifier} as {identifierType}.
        slots:
          identifier: path.identifier
          identifierType: query.identifierType
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contacts/{identifier}/campaignStats'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a contact's email campaign stats
      effect: read
      questions:
      - Which of my campaigns has a specific contact opened or clicked?
      - Can I see bounces and unsubscribes for one contact over a date range?
      instructions:
      - text: Show email campaign statistics for contact {identifier}.
        slots:
          identifier: path.identifier
      - text: Get opens and clicks for {identifier} from {startDate} to {endDate}.
        slots:
          identifier: path.identifier
          startDate: query.startDate
          endDate: query.endDate
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contacts/segments'].get
  update:
    x-apievangelist-phrasing:
      intent: List contact segments
      effect: read
      questions:
      - What segments have I defined for my contacts?
      - How many segments can be returned per page at most?
      instructions:
      - text: List all my contact segments.
      - text: Show {limit} segments sorted {sort}.
        slots:
          limit: query.limit
          sort: query.sort
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contacts/export'].post
  update:
    x-apievangelist-phrasing:
      intent: Export contacts to CSV
      effect: write
      questions:
      - Can I export a filtered set of my contacts to a CSV file?
      - How will I know when my contact export file is ready?
      instructions:
      - text: Export contacts matching {customContactFilter} to CSV.
        slots:
          customContactFilter: requestBody.customContactFilter
      - text: Export contacts matching {customContactFilter} and notify {notifyUrl} when done.
        slots:
          customContactFilter: requestBody.customContactFilter
          notifyUrl: requestBody.notifyUrl
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contacts/import'].post
  update:
    x-apievangelist-phrasing:
      intent: Import contacts in bulk
      effect: write
      questions:
      - Can I bulk import contacts from a CSV file URL?
      - What happens to attributes in my import that don't exist in the account?
      - Is it possible to import contacts into a brand-new list?
      instructions:
      - text: Import contacts from {fileUrl} into lists {listIds}.
        slots:
          fileUrl: requestBody.fileUrl
          listIds: requestBody.listIds
      - text: Import these contacts {jsonBody} and update existing ones.
        slots:
          jsonBody: requestBody.jsonBody
      method: generated
      generated: '2026-09-26'