Microsoft Azure Voice Services Provisioning Platform API

swagger: '2.0'
info:
  title: Microsoft Azure Microsoft.VoiceServices.ACG.ProvisioningPlatform.API
  version: '2023-10-01'
securityDefinitions:
  OAuth2:
    type: oauth2
    description: Azure Active Directory OAuth2 Flow.
    flow: application
    tokenUrl: https://login.microsoftonline.com/common/oauth2/v2.0/token
    scopes:
      https://func-voiceservice-rp-prod-eastuseuap.azurewebsites.net/.default: Grants the associated roles assigned to the client application
security:
  - OAuth2:
      - https://func-voiceservice-rp-prod-eastuseuap.azurewebsites.net/.default
paths:
  /account/{accountName}/numbers:
    get:
      operationId: microsoftAzureAccountListnumbers
      produces:
        - application/json
      parameters:
        - in: path
          name: accountName
          pattern: ^([A-Za-z0-9_-]+)$
          minLength: 1
          maxLength: 100
          required: true
          type: string
          description: >-
            Name of the account. Can only contain letters, numbers, underscores
            and dashes, and is case-sensitive. Can be up to 100 characters in
            length.
        - $ref: '#/parameters/ApiVersionParameter'
        - format: int32
          in: query
          name: maxpagesize
          type: integer
          description: >-
            Maximum number of records to include in a single response. Defaults
            to 200, and must not exceed 500.
        - format: int32
          in: query
          name: skip
          type: integer
          description: An offset into the collection of the first record to be returned.
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/NumbersList'
        default:
          description: An error response object.
          headers:
            x-ms-error-code:
              type: string
              description: Error code for specific error that occurred.
          schema:
            $ref: '#/definitions/ErrorResponse'
      x-ms-pageable:
        nextLinkName: nextLink
      x-ms-examples:
        Get account numbers.:
          $ref: ./examples/GetAccountNumbers.json
      tags:
        - Number
      description: >-
        Gets a list of the numbers assigned to the specified account. Response
        pagination can be controlled with a combination of the maxpagesize and
        skip parameters. Limit the number of records in a response with the
        maxpagesize parameter. Specify the starting record using the skip
        parameter.
      summary: Microsoft Azure Get Account Accountname Numbers
  /account/{accountName}/numbers:batch:
    post:
      operationId: microsoftAzureAccountCreateorreplacenumbers
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: path
          name: accountName
          pattern: ^([A-Za-z0-9_-]+)$
          minLength: 1
          maxLength: 100
          required: true
          type: string
          description: >-
            Name of the account. Can only contain letters, numbers, underscores
            and dashes, and is case-sensitive. Can be up to 100 characters in
            length.
        - $ref: '#/parameters/ApiVersionParameter'
        - in: body
          name: body
          required: true
          schema:
            $ref: '#/definitions/BatchNumbers'
          description: Batch of numbers to create or replace.
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/BatchNumbersResponse'
        default:
          description: An error response object.
          headers:
            x-ms-error-code:
              type: string
              description: Error code for specific error that occurred.
          schema:
            $ref: '#/definitions/ErrorResponse'
      x-ms-examples:
        Batch put numbers.:
          $ref: ./examples/BatchPutNumbers.json
      tags:
        - BatchNumbers
      description: >-
        Adds or replaces between 1 and 100 numbers (inclusive) in the specified
        account. In the body, specify a list of phone numbers and and the
        corresponding details (for example, the services to enable) for each
        number. This operation is atomic; if any item fails, then all items
        fail.
      summary: Microsoft Azure Post Account Accountname Numbers:batch
  /account/{accountName}/numbers/{phoneNumber}:
    delete:
      operationId: microsoftAzureNumberDelete
      produces:
        - application/json
      parameters:
        - in: path
          name: accountName
          pattern: ^([A-Za-z0-9_-]+)$
          minLength: 1
          maxLength: 100
          required: true
          type: string
          description: >-
            Name of the account. Can only contain letters, numbers, underscores
            and dashes, and is case-sensitive. Can be up to 100 characters in
            length.
        - in: path
          name: phoneNumber
          pattern: ^\+[1-9]\d+$
          minLength: 3
          maxLength: 16
          required: true
          type: string
          description: Phone number in E.164 format.
        - $ref: '#/parameters/ApiVersionParameter'
      responses:
        '204':
          description: No Content
        default:
          description: An error response object.
          headers:
            x-ms-error-code:
              type: string
              description: Error code for specific error that occurred.
          schema:
            $ref: '#/definitions/ErrorResponse'
      x-ms-examples:
        Delete a number.:
          $ref: ./examples/DeleteNumber.json
      tags:
        - Number
      description: Removes the specified number from the specified account.
      summary: Microsoft Azure Delete Account Accountname Numbers Phonenumber
    get:
      operationId: microsoftAzureNumberGet
      produces:
        - application/json
      parameters:
        - in: path
          name: accountName
          pattern: ^([A-Za-z0-9_-]+)$
          minLength: 1
          maxLength: 100
          required: true
          type: string
          description: >-
            Name of the account. Can only contain letters, numbers, underscores
            and dashes, and is case-sensitive. Can be up to 100 characters in
            length.
        - in: path
          name: phoneNumber
          pattern: ^\+[1-9]\d+$
          minLength: 3
          maxLength: 16
          required: true
          type: string
          description: Phone number in E.164 format.
        - $ref: '#/parameters/ApiVersionParameter'
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/NumberResponse'
        default:
          description: An error response object.
          headers:
            x-ms-error-code:
              type: string
              description: Error code for specific error that occurred.
          schema:
            $ref: '#/definitions/ErrorResponse'
      x-ms-examples:
        Get a number.:
          $ref: ./examples/GetNumber.json
      tags:
        - Number
      description: >-
        Gets the details of a number assigned to an account, including the
        services for which the number is enabled.
      summary: Microsoft Azure Get Account Accountname Numbers Phonenumber
    put:
      operationId: microsoftAzureNumberCreateorreplace
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: path
          name: accountName
          pattern: ^([A-Za-z0-9_-]+)$
          minLength: 1
          maxLength: 100
          required: true
          type: string
          description: >-
            Name of the account. Can only contain letters, numbers, underscores
            and dashes, and is case-sensitive. Can be up to 100 characters in
            length.
        - in: path
          name: phoneNumber
          pattern: ^\+[1-9]\d+$
          minLength: 3
          maxLength: 16
          required: true
          type: string
          description: Phone number in E.164 format.
        - $ref: '#/parameters/ApiVersionParameter'
        - in: header
          name: If-Match
          type: string
          description: Makes a request conditional on a matching etag.
        - in: header
          name: If-None-Match
          type: string
          description: Makes a request conditional on a non-matching etag.
        - in: body
          name: body
          required: true
          schema:
            $ref: '#/definitions/NumberDetails'
          description: New details of the number to create or replace.
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/NumberResponse'
        '201':
          description: Created
          schema:
            $ref: '#/definitions/NumberResponse'
        default:
          description: An error response object.
          headers:
            x-ms-error-code:
              type: string
              description: Error code for specific error that occurred.
          schema:
            $ref: '#/definitions/ErrorResponse'
      x-ms-examples:
        Put a number.:
          $ref: ./examples/PutNumber.json
      tags:
        - Number
      description: >-
        Creates or replaces the specified number in the specified account. In
        the body of the request, include the service for which this number is
        enabled. If the service is not specified, Operator Connect service is
        enabled by default. Optionally, include additional configuration for the
        number.
      summary: Microsoft Azure Put Account Accountname Numbers Phonenumber
  /accounts:
    get:
      operationId: microsoftAzureAccountsList
      produces:
        - application/json
      parameters:
        - $ref: '#/parameters/ApiVersionParameter'
        - format: int32
          in: query
          name: maxpagesize
          type: integer
          description: >-
            Maximum number of records to include in a single response. Defaults
            to 200, and must not exceed 500.
        - format: int32
          in: query
          name: skip
          type: integer
          description: An offset into the collection of the first record to be returned.
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/AccountsList'
        default:
          description: An error response object.
          headers:
            x-ms-error-code:
              type: string
              description: Error code for specific error that occurred.
          schema:
            $ref: '#/definitions/ErrorResponse'
      x-ms-pageable:
        nextLinkName: nextLink
      tags:
        - Account
      description: >-
        Gets a list of account records. An account represents a customer to
        which you are providing service. Response pagination can be controlled
        with a combination of the maxpagesize and skip parameters. Limit the
        number of records in a response with the maxpagesize parameter. Specify
        the starting record using the skip parameter.
      x-ms-examples:
        Get a list of account records.:
          $ref: ./examples/GetAccounts.json
      summary: Microsoft Azure Get Accounts
  /accounts/{accountName}:
    delete:
      operationId: microsoftAzureAccountDelete
      produces:
        - application/json
      parameters:
        - in: path
          name: accountName
          pattern: ^([A-Za-z0-9_-]+)$
          minLength: 1
          maxLength: 100
          required: true
          type: string
          description: >-
            Name of the account. Can only contain letters, numbers, underscores
            and dashes, and is case-sensitive. Can be up to 100 characters in
            length.
        - $ref: '#/parameters/ApiVersionParameter'
      responses:
        '204':
          description: No Content
        default:
          description: An error response object.
          headers:
            x-ms-error-code:
              type: string
              description: Error code for specific error that occurred.
          schema:
            $ref: '#/definitions/ErrorResponse'
      x-ms-examples:
        Delete an account:
          $ref: ./examples/DeleteAccount.json
      tags:
        - Account
      description: Deletes an account (representing a customer).
      summary: Microsoft Azure Delete Accounts Accountname
    get:
      operationId: microsoftAzureAccountGet
      produces:
        - application/json
      parameters:
        - in: path
          name: accountName
          pattern: ^([A-Za-z0-9_-]+)$
          minLength: 1
          maxLength: 100
          required: true
          type: string
          description: >-
            Name of the account. Can only contain letters, numbers, underscores
            and dashes. Can be up to 100 characters in length.
        - $ref: '#/parameters/ApiVersionParameter'
        - name: status
          in: query
          default: false
          required: false
          type: boolean
          description: >-
            Additionally return the provisioning state of the backends
            configured for this account (e.g. DNS subdomain provisioning for
            Microsoft Teams Direct Routing).
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/AccountWithStatusResponse'
        default:
          description: An error response object.
          headers:
            x-ms-error-code:
              type: string
              description: Error code for specific error that occurred.
          schema:
            $ref: '#/definitions/ErrorResponse'
      x-ms-examples:
        Get information about an account:
          $ref: ./examples/GetAccount.json
      tags:
        - Account
      description: >-
        Gets the details of the specified account. An account represents a
        customer.
      summary: Microsoft Azure Get Accounts Accountname
    put:
      operationId: microsoftAzureAccountCreateorreplace
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: path
          name: accountName
          pattern: ^([A-Za-z0-9_-]+)$
          minLength: 1
          maxLength: 100
          required: true
          type: string
          description: >-
            Name of the account. Can only contain letters, numbers, underscores
            and dashes, and is case-sensitive. Can be up to 100 characters in
            length.
        - $ref: '#/parameters/ApiVersionParameter'
        - in: header
          name: If-Match
          type: string
          description: Makes a request conditional on a matching etag.
        - in: header
          name: If-None-Match
          type: string
          description: Makes a request conditional on a non-matching etag.
        - in: body
          name: body
          required: true
          schema:
            $ref: '#/definitions/AccountDetails'
          description: New details of the account to create or replace.
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/AccountResponse'
        '201':
          description: Created
          schema:
            $ref: '#/definitions/AccountResponse'
        default:
          description: An error response object.
          headers:
            x-ms-error-code:
              type: string
              description: Error code for specific error that occurred.
          schema:
            $ref: '#/definitions/ErrorResponse'
      x-ms-examples:
        Put new information about an account:
          $ref: ./examples/PutAccount.json
      tags:
        - Account
      description: >-
        Creates or replaces the specified account, representing a customer. In
        the body of the request, include additional service-specific
        configuration. For example, for Microsoft Teams Direct Routing, specify
        the customer-specific subdomain label and DNS TXT values from the
        customer's Microsoft 365 configuration.
      summary: Microsoft Azure Put Accounts Accountname
  /numbers:
    get:
      operationId: microsoftAzureNumbersList
      produces:
        - application/json
      parameters:
        - $ref: '#/parameters/ApiVersionParameter'
        - in: query
          name: number
          pattern: ^\+[1-9]\d+$
          minLength: 1
          maxLength: 16
          type: string
          description: Query information for a specific number.
        - format: int32
          in: query
          name: maxpagesize
          type: integer
          description: >-
            Maximum number of records to include in a single response. Defaults
            to 200, and must not exceed 500.
        - format: int32
          in: query
          name: skip
          type: integer
          description: An offset into the collection of the first record to be returned.
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/NumbersList'
        default:
          description: An error response object.
          headers:
            x-ms-error-code:
              type: string
              description: Error code for specific error that occurred.
          schema:
            $ref: '#/definitions/ErrorResponse'
      x-ms-pageable:
        nextLinkName: nextLink
      x-ms-examples:
        Get all numbers configured on the provisioning platform.:
          $ref: ./examples/GetNumbers.json
      tags:
        - Numbers
      description: >-
        Gets a list of all configured numbers across all accounts. Response
        pagination can be controlled with a combination of the maxpagesize and
        skip parameters. Limit the number of records in a response with the
        maxpagesize parameter. Specify the starting record using the skip
        parameter.
      summary: Microsoft Azure Get Numbers
definitions:
  AccountDetails:
    additionalProperties: false
    properties:
      directRouting:
        $ref: '#/definitions/TeamsDrConfig'
    type: object
    description: Details of the account.
  AccountResponse:
    additionalProperties: false
    properties:
      etag:
        type: string
        description: ETag for use with If-Match headers for optimistic concurrency.
      name:
        minLength: 1
        type: string
        description: Name of the account.
      details:
        $ref: '#/definitions/AccountDetails'
    required:
      - name
    type: object
    description: Details of the account as returned on a GET request.
  AccountsList:
    additionalProperties: false
    properties:
      value:
        items:
          $ref: '#/definitions/AccountResponse'
        type: array
        description: List of account records.
      nextLink:
        type: string
        format: uri
        description: Link to the next page of results.
    required:
      - value
    type: object
    description: Paginated list of records for an account.
  AccountWithStatusResponse:
    additionalProperties: false
    properties:
      etag:
        type: string
        description: ETag for use with If-Match headers for optimistic concurrency.
      name:
        minLength: 1
        type: string
        description: Name of the account.
      details:
        $ref: '#/definitions/AccountDetails'
      directRoutingProvisioningState:
        $ref: '#/definitions/SubdomainProvisioningState'
    required:
      - name
    type: object
    description: >-
      Details of the account and its DNS provisioning status as returned on a
      GET request.
  BatchNumbers:
    additionalProperties: false
    description: Batch of numbers with configuration.
    properties:
      numbers:
        items:
          $ref: '#/definitions/BatchNumbersItem'
        maxItems: 100
        type: array
        description: Records to use for create/replace.
    required:
      - numbers
    type: object
  BatchNumbersItem:
    additionalProperties: false
    description: Details for a single number.
    properties:
      details:
        $ref: '#/definitions/NumberDetails'
      phoneNumber:
        pattern: ^\+[1-9]\d+$
        minLength: 3
        maxLength: 16
        type: string
        description: The E.164 phone number whose record should be created/replaced.
    required:
      - details
      - phoneNumber
    type: object
  BatchNumbersResponse:
    additionalProperties: false
    properties:
      numbers:
        items:
          $ref: '#/definitions/NumberResponse'
        type: array
        description: Details of the created/replaced numbers.
    required:
      - numbers
    type: object
    description: List of created or replaced numbers.
  NumberConfiguration:
    additionalProperties: false
    properties:
      customSipHeader:
        pattern: ^([A-Za-z0-9_-])+$
        minLength: 1
        maxLength: 100
        type: string
        description: >-
          Contents of the custom SIP header to use with this number. Can only
          contain letters, numbers, underscores and dashes. Can be up to 100
          characters in length. The name of the custom header is set as part of
          deploying Azure Communications Gateway.
    type: object
    description: Configuration for this number.
  NumberDetails:
    additionalProperties: false
    properties:
      configuration:
        $ref: '#/definitions/NumberConfiguration'
      services:
        $ref: '#/definitions/NumberServices'
    required:
      - services
    type: object
    description: Details of the number.
  NumberResponse:
    additionalProperties: false
    properties:
      etag:
        type: string
        description: ETag for use with If-Match headers for optimistic concurrency.
      accountName:
        minLength: 1
        type: string
        description: Account name which owns this number.
      phoneNumber:
        minLength: 1
        type: string
        description: The phone number corresponding to this entry.
      details:
        $ref: '#/definitions/NumberDetails'
    required:
      - accountName
      - details
      - phoneNumber
    type: object
    description: Details of the number as returned on a GET request.
  NumbersList:
    additionalProperties: false
    properties:
      value:
        items:
          $ref: '#/definitions/NumberResponse'
        type: array
        description: Number of records for the page.
      nextLink:
        type: string
        format: uri
        description: Link to the next page of results.
    required:
      - value
    type: object
    description: List of number records.
  NumberServices:
    additionalProperties: false
    properties:
      teamsDrEnabled:
        type: boolean
        description: Enables/disables Microsoft Teams Direct Routing for the number.
      teamsOcEnabled:
        type: boolean
        description: Enables/disables Operator Connect for the number.
      zoomEnabled:
        type: boolean
        description: Enables/disables Zoom for the number.
    required:
      - teamsDrEnabled
      - teamsOcEnabled
      - zoomEnabled
    type: object
    description: Communications services enabled for this number.
  SubdomainProvisioningState:
    additionalProperties: false
    properties:
      subdomainTokens:
        $ref: '#/definitions/TeamsDrSubdomainTokens'
      subdomainStatus:
        $ref: '#/definitions/SubdomainProvisioningStatus'
    required:
      - subdomainStatus
    type: object
    description: Status of DNS configuration and the DNS TXT values for the DNS records
  SubdomainProvisioningStatus:
    enum:
      - Provisioned
      - NotProvisioned
      - Inconsistent
    type: string
    description: >-
      Status of DNS configuration. Azure Communications Gateway generates DNS
      records to Microsoft 365 to verify that the customer-specific domain name
      is associated with the correct customer tenant.
    x-ms-enum:
      name: SubdomainProvisioningStatus
      modelAsString: true
      values:
        - value: Provisioned
          description: DNS state is provisioned.
          name: Provisioned
        - value: NotProvisioned
          description: DNS state has not been provisioned.
          name: NotProvisioned
        - value: Inconsistent
          description: The programmed DNS state doesn't match the requested programming.
          name: Inconsistent
  TeamsDrConfig:
    additionalProperties: false
    properties:
      callScreening:
        type: boolean
        description: >-
          Enables/disables caller ID screening for the account. Caller ID
          screening is enabled by default.
      subdomain:
        pattern: ^([A-Za-z0-9_-]+)$
        minLength: 1
        maxLength: 10
        type: string
        description: >-
          Customer-specific domain name label. Can only contain letters,
          numbers, underscores and dashes. Can be up to 10 characters in length.
      subdomainTokens:
        $ref: '#/definitions/TeamsDrSubdomainTokens'
    required:
      - callScreening
      - subdomain
      - subdomainTokens
    type: object
    description: Account configuration relating to Microsoft Teams Direct Routing.
  TeamsDrSubdomainTokens:
    additionalProperties: false
    properties:
      region1Token:
        pattern: ^([A-Za-z0-9=_-]+)$
        minLength: 1
        maxLength: 100
        type: string
        description: >-
          DNS TXT value for the first region, as provided by the customer from
          their Microsoft 365 Admin Center. Can only contain letters, numbers,
          underscores and dashes. Can be up to 100 characters in length.
      region2Token:
        pattern: ^([A-Za-z0-9=_-]+)$
        minLength: 1
        maxLength: 100
        type: string
        description: >-
          DNS TXT value for the first region, as provided by the customer from
          their Microsoft 365 Admin Center. Can only contain letters, numbers,
          underscores and dashes. Can be up to 100 characters in length.
    required:
      - region1Token
      - region2Token
    type: object
    description: DNS TXT values (tokens) for the account.
  ErrorResponse:
    title: Error details.
    description: Contains details when the response code indicates an error.
    type: object
    properties:
      error:
        description: The error details.
        $ref: '#/definitions/ErrorDetail'
    required:
      - error
  ErrorDetail:
    title: The code and message for an error.
    type: object
    properties:
      code:
        description: A machine readable error code.
        type: string
      message:
        description: A human readable representation of the error.
        type: string
      details:
        description: An array of details about specific errors that led to this error.
        type: array
        items:
          $ref: '#/definitions/ErrorDetail'
      innererror:
        description: An object containing more specific information about the error.
        $ref: '#/definitions/InnerError'
      additionalProperties:
        description: Additional properties that can be provided about the error.
    required:
      - code
      - message
  InnerError:
    title: More specific information on an error object.
    type: object
    properties:
      code:
        description: A machine readable error code.
        type: string
      innererror:
        description: Inner error details if they exist.
        $ref: '#/definitions/InnerError'
x-components: {}
parameters:
  ApiVersionParameter:
    name: api-version
    in: query
    required: true
    type: string
    description: Client API version
    x-ms-parameter-location: client
tags:
  - name: Account
  - name: BatchNumbers
  - name: Number
  - name: Numbers