# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Microsoft Azure Number API
  version: 1.0.0
extends: openapi/microsoft-azure-number-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: 8
- target: $.paths['/account/{accountName}/numbers'].get
  update:
    x-apievangelist-phrasing:
      intent: List numbers assigned to a voice account
      effect: read
      questions:
      - Which phone numbers are assigned to my Operator Connect provisioning account?
      - Can I page through account numbers using maxpagesize and skip?
      instructions:
      - text: List the numbers assigned to account {account}.
        slots:
          account: path.accountName
      - text: Show {size} numbers on account {account}, skipping the first {skip}.
        slots:
          size: query.maxpagesize
          account: path.accountName
          skip: query.skip
      method: generated
      generated: '2026-09-26'
- target: $.paths['/account/{accountName}/numbers/{phoneNumber}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a number and its enabled services
      effect: read
      questions:
      - Which services is a particular phone number enabled for on my account?
      - How do I look up one assigned number under the singular account path?
      instructions:
      - text: Get number {phone} on account {account} with its enabled services.
        slots:
          phone: path.phoneNumber
          account: path.accountName
      - text: Show which services phone number {phone} has on account {account}.
        slots:
          phone: path.phoneNumber
          account: path.accountName
      method: generated
      generated: '2026-09-26'
- target: $.paths['/account/{accountName}/numbers/{phoneNumber}'].put
  update:
    x-apievangelist-phrasing:
      intent: Assign a number to an account with services
      effect: write
      questions:
      - How do I add a phone number to an account and enable Operator Connect on it?
      - What service is enabled if I do not specify one when assigning a number?
      instructions:
      - text: Assign number {phone} to account {account} with services {services}.
        slots:
          phone: path.phoneNumber
          account: path.accountName
          services: requestBody.services
      - text: Replace number {phone} on account {account} with services {services} and configuration {config}.
        slots:
          phone: path.phoneNumber
          account: path.accountName
          services: requestBody.services
          config: requestBody.configuration
      method: generated
      generated: '2026-09-26'
- target: $.paths['/account/{accountName}/numbers/{phoneNumber}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a number from an account
      effect: destructive
      questions:
      - How do I unassign a phone number from my voice services account?
      - Can I release one number without affecting the rest of the account?
      instructions:
      - text: Remove number {phone} from account {account}.
        slots:
          phone: path.phoneNumber
          account: path.accountName
      - text: Unassign phone number {phone} from voice account {account}.
        slots:
          phone: path.phoneNumber
          account: path.accountName
      method: generated
      generated: '2026-09-26'
- target: $.paths['/accounts/{accountName}/numbers'].get
  update:
    x-apievangelist-phrasing:
      intent: List Numbers on a provisioning platform account
      effect: read
      questions:
      - How do I filter the Numbers on an accounts-path provisioning account?
      - Can I get a total count of telephone numbers along with the list?
      instructions:
      - text: List the Numbers on provisioning account {account} matching filter {filter}.
        slots:
          account: path.accountName
          filter: query.filter
      - text: Return the top {top} telephone numbers on account {account} with record counts {count}.
        slots:
          top: query.top
          account: path.accountName
          count: query.countRecords
      method: generated
      generated: '2026-09-26'
- target: $.paths['/accounts/{accountName}/numbers/{telephoneNumber}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a Number by telephone number
      effect: read
      questions:
      - What is the provisioning status of a telephone number on my accounts-path account?
      - Can I fetch a Number only if it changed since a given time?
      instructions:
      - text: Get telephone number {tel} on provisioning account {account}.
        slots:
          tel: path.telephoneNumber
          account: path.accountName
      - text: Fetch Number {tel} on account {account} only if modified since {since}.
        slots:
          tel: path.telephoneNumber
          account: path.accountName
          since: header.If-Modified-Since
      method: generated
      generated: '2026-09-26'
- target: $.paths['/accounts/{accountName}/numbers/{telephoneNumber}'].put
  update:
    x-apievangelist-phrasing:
      intent: Create or replace a Number's service details
      effect: write
      questions:
      - How do I provision a telephone number with its service details on the provisioning platform?
      - Can I safely retry a Number create using a repeatability request ID?
      instructions:
      - text: Create telephone number {tel} on provisioning account {account} with service details {details}.
        slots:
          tel: path.telephoneNumber
          account: path.accountName
          details: requestBody.serviceDetails
      - text: Replace Number {tel} on account {account} with service details {details}, repeatability ID {rid}.
        slots:
          tel: path.telephoneNumber
          account: path.accountName
          details: requestBody.serviceDetails
          rid: header.Repeatability-Request-ID
      method: generated
      generated: '2026-09-26'
- target: $.paths['/accounts/{accountName}/numbers/{telephoneNumber}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a Number by telephone number
      effect: destructive
      questions:
      - How do I deprovision a telephone number from the provisioning platform?
      - Can I delete a Number only if its ETag still matches?
      instructions:
      - text: Delete telephone number {tel} from provisioning account {account}.
        slots:
          tel: path.telephoneNumber
          account: path.accountName
      - text: Deprovision Number {tel} on account {account} if it matches ETag {etag}.
        slots:
          tel: path.telephoneNumber
          account: path.accountName
          etag: header.If-Match
      method: generated
      generated: '2026-09-26'