# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Zoom Phone Phone Numbers API
  version: 1.0.0
extends: openapi/zoom-phone-phone-numbers-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-01'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 14
- target: $.paths['/phone/byoc_numbers'].post
  update:
    x-apievangelist-phrasing:
      intent: Add bring-your-own-carrier numbers to Zoom Phone
      effect: write
      questions:
      - How do I bring my own carrier's phone numbers into Zoom Phone?
      - Can I attach BYOC numbers to a SIP group when I add them under the phone endpoint?
      instructions:
      - text: Add BYOC numbers {phone_numbers} from carrier {carrier} to Zoom Phone.
        slots:
          phone_numbers: requestBody.phone_numbers
          carrier: requestBody.carrier
      - text: Add BYOC numbers {phone_numbers} from {carrier} to site {site_id} via the Zoom Phone endpoint.
        slots:
          phone_numbers: requestBody.phone_numbers
          carrier: requestBody.carrier
          site_id: requestBody.site_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/phone/numbers'].get
  update:
    x-apievangelist-phrasing:
      intent: List the account's Zoom Phone numbers
      effect: read
      questions:
      - Which Zoom Phone numbers in our account are still unassigned?
      - Can I filter Zoom Phone numbers by site or by toll-free vs toll number type?
      instructions:
      - text: List all Zoom Phone numbers on the account.
      - text: List {type} Zoom Phone numbers at site {site_id}.
        slots:
          type: query.type
          site_id: query.site_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/phone/numbers'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete unassigned Zoom Phone numbers
      effect: destructive
      questions:
      - How do I release Zoom Phone numbers nobody is using?
      - Is there a cap on how many unassigned numbers I can delete in one request?
      instructions:
      - text: Delete unassigned Zoom Phone numbers {phone_numbers}.
        slots:
          phone_numbers: query.phone_numbers
      - text: Release the unused numbers {phone_numbers} from Zoom Phone, up to 20 at once.
        slots:
          phone_numbers: query.phone_numbers
      method: generated
      generated: '2026-10-01'
- target: $.paths['/phone/numbers/sites/{siteId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Move unassigned numbers to a site
      effect: write
      questions:
      - How do I move spare phone numbers from one site to another?
      - Can I reassign up to 20 unassigned numbers to a different site at once?
      instructions:
      - text: Move unassigned numbers {phone_numbers} to site {siteId}.
        slots:
          siteId: path.siteId
          phone_numbers: requestBody.phone_numbers
      - text: Update site {siteId}'s unassigned phone numbers.
        slots:
          siteId: path.siteId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/phone/numbers/{phoneNumberId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a Zoom Phone number's details
      effect: read
      questions:
      - Who is a specific Zoom Phone number assigned to?
      - What capabilities and emergency address status does a Zoom Phone number have?
      instructions:
      - text: Show Zoom Phone number {phoneNumberId}.
        slots:
          phoneNumberId: path.phoneNumberId
      - text: Get the assignee and status of Zoom Phone number {phoneNumberId}.
        slots:
          phoneNumberId: path.phoneNumberId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/phone/numbers/{phoneNumberId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a Zoom Phone number
      effect: write
      questions:
      - How do I set a Zoom Phone number to SMS-only or voice-only capability?
      - Can I change a Zoom Phone number's display name or SIP group?
      instructions:
      - text: Set the capability of Zoom Phone number {phoneNumberId} to {capability}.
        slots:
          phoneNumberId: path.phoneNumberId
          capability: requestBody.capability
      - text: Rename Zoom Phone number {phoneNumberId} to {display_name}.
        slots:
          phoneNumberId: path.phoneNumberId
          display_name: requestBody.display_name
      method: generated
      generated: '2026-10-01'
- target: $.paths['/phone/users/{userId}/phone_numbers'].post
  update:
    x-apievangelist-phrasing:
      intent: Assign a phone number to a user
      effect: write
      questions:
      - How do I give a Zoom Phone user a direct phone number?
      - Does a user need Zoom Phone enabled before I can assign them a number?
      instructions:
      - text: Assign {phone_numbers} to user {userId}.
        slots:
          userId: path.userId
          phone_numbers: requestBody.phone_numbers
      - text: Give user {userId} a phone number.
        slots:
          userId: path.userId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/phone/users/{userId}/phone_numbers/{phoneNumberId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Unassign a phone number from a user
      effect: destructive
      questions:
      - How do I take a phone number away from a Zoom Phone user?
      - Can I remove a number from someone who's leaving the company?
      instructions:
      - text: Unassign phone number {phoneNumberId} from user {userId}.
        slots:
          userId: path.userId
          phoneNumberId: path.phoneNumberId
      - text: Remove number {phoneNumberId} from user {userId}'s phone.
        slots:
          userId: path.userId
          phoneNumberId: path.phoneNumberId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/number_management/allocation'].patch
  update:
    x-apievangelist-phrasing:
      intent: Allocate or unallocate numbers to a product
      effect: write
      questions:
      - How do I allocate phone numbers with CPL routing to a Zoom product?
      - Must allocated native numbers share the same country and number plan?
      instructions:
      - text: Allocate numbers {numbers} to {allocated_product}.
        slots:
          numbers: requestBody.numbers
          allocated_product: requestBody.allocated_product
      - text: Allocate {numbers} to {allocated_product} at site {site_id}.
        slots:
          numbers: requestBody.numbers
          allocated_product: requestBody.allocated_product
          site_id: requestBody.site_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/number_management/byoc_numbers'].post
  update:
    x-apievangelist-phrasing:
      intent: Add BYOC numbers in number management
      effect: write
      questions:
      - Can I add carrier numbers through number management and allocate them to a product?
      - Is PCI Pal supported for BYOC numbers added in number management?
      instructions:
      - text: Add BYOC numbers {phone_numbers} in number management allocated to {allocated_product}.
        slots:
          phone_numbers: requestBody.phone_numbers
          allocated_product: requestBody.allocated_product
      - text: Register BYOC numbers {phone_numbers} for {allocated_product} with country {country_iso} in number management.
        slots:
          phone_numbers: requestBody.phone_numbers
          allocated_product: requestBody.allocated_product
          country_iso: requestBody.country_iso
      method: generated
      generated: '2026-10-01'
- target: $.paths['/number_management/numbers'].get
  update:
    x-apievangelist-phrasing:
      intent: List numbers in number management
      effect: read
      questions:
      - What phone numbers does number management show, filtered by allocated product or status?
      - Can I search number management by keyword or who a number is assigned to?
      instructions:
      - text: List all numbers in number management.
      - text: List number management numbers allocated to {allocated_product} with status {number_status}.
        slots:
          allocated_product: query.allocated_product
          number_status: query.number_status
      method: generated
      generated: '2026-10-01'
- target: $.paths['/number_management/numbers'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete numbers in number management
      effect: destructive
      questions:
      - How do I delete phone numbers through number management?
      - Can I permanently remove several numbers from the master account?
      instructions:
      - text: Delete numbers {numbers} from number management.
        slots:
          numbers: query.numbers
      - text: Remove phone numbers {numbers} using number management.
        slots:
          numbers: query.numbers
      method: generated
      generated: '2026-10-01'
- target: $.paths['/number_management/numbers/{phoneNumberId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a number from number management
      effect: read
      questions:
      - What does number management record about a single phone number?
      - Can I see a number's allocated product and source in number management?
      instructions:
      - text: Show number management details for number {phoneNumberId}.
        slots:
          phoneNumberId: path.phoneNumberId
      - text: Look up number {phoneNumberId} in number management.
        slots:
          phoneNumberId: path.phoneNumberId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/number_management/numbers/{phoneNumberId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a number in number management
      effect: write
      questions:
      - How do I change a number's caller ID name in number management?
      - Can I confirm an emergency address update while editing a number in number management?
      instructions:
      - text: Set the caller ID name of number {phoneNumberId} to {caller_id_name} in number management.
        slots:
          phoneNumberId: path.phoneNumberId
          caller_id_name: requestBody.caller_id_name
      - text: Update number management entry {phoneNumberId} with SIP group {sip_group_id}.
        slots:
          phoneNumberId: path.phoneNumberId
          sip_group_id: requestBody.sip_group_id
      method: generated
      generated: '2026-10-01'