Microsoft Azure Communication Services Obtain operator information for requested numbers API

openapi: 3.2.0
info:
  title: PhoneNumbersClient Obtain operator information for…
  description: The phone numbers client uses Azure Communication Services to purchase and manage phone numbers.
  version: '2025-06-01'
tags:
- name: Obtain operator information for requested numbers
paths:
  /operatorInformation/:search:
    post:
      tags:
      - Obtain operator information for requested numbers
      summary: Searches for number format and operator information for a given list of phone…
      operationId: PhoneNumbers_OperatorInformationSearch
      parameters:
      - $ref: '#/components/parameters/ApiVersionParameter'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperatorInformationResult'
        default:
          description: Failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommunicationErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OperatorInformationRequest'
        description: The phone number(s) whose number format and operator information should be searched
        required: true
components:
  schemas:
    OperatorInformationResult:
      description: Represents a search result containing format and operator information associated with the requested phone numbers
      type: object
      properties:
        values:
          description: 'Results of a search.

            This array will have one entry per requested phone number which will contain the relevant operator information.'
          type: array
          items:
            $ref: '#/components/schemas/OperatorInformation'
    OperatorDetails:
      description: Represents metadata describing the operator of a phone number
      type: object
      properties:
        name:
          description: Name of the phone operator
          type: string
        mobileNetworkCode:
          description: Mobile Network Code, 2 or 3 decimal digits that identify mobile networks within a country/region
          type: string
        mobileCountryCode:
          description: Mobile Country Code, 3 decimal digits that identify a country/region
          type: string
    OperatorInformationRequest:
      description: Represents a search request for operator information for the given phone numbers.
      required:
      - phoneNumbers
      type: object
      properties:
        phoneNumbers:
          description: Phone number(s) whose operator information is being requested
          type: array
          items:
            type: string
        options:
          $ref: '#/components/schemas/OperatorInformationOptions'
    OperatorInformationOptions:
      description: Represents options to modify a search request for operator information
      type: object
      properties:
        includeAdditionalOperatorDetails:
          description: 'Includes the fields operatorDetails, numberType, and isoCountryCode in the response.  Please note: use of this option will result in additional costs'
          type: boolean
    CommunicationErrorResponse:
      description: The Communication Services error.
      type: object
      required:
      - error
      properties:
        error:
          description: The Communication Services error.
          $ref: '#/components/schemas/CommunicationError'
    OperatorInformation:
      description: Represents metadata about a phone number that is controlled/provided by that phone number's operator.
      required:
      - phoneNumber
      type: object
      properties:
        phoneNumber:
          description: E.164 formatted string representation of the phone number
          type: string
        nationalFormat:
          description: National format of the phone number
          type: string
        internationalFormat:
          description: International format of the phone number
          type: string
        isoCountryCode:
          description: ISO 3166-1 two character ('alpha-2') code associated with the phone number.
          type: string
        numberType:
          description: Type of service associated with the phone number
          enum:
          - unknown
          - other
          - geographic
          - mobile
          type: string
          x-ms-enum:
            name: OperatorNumberType
            modelAsString: true
        operatorDetails:
          $ref: '#/components/schemas/OperatorDetails'
    CommunicationError:
      description: The Communication Services error.
      type: object
      required:
      - code
      - message
      properties:
        code:
          type: string
          description: The error code.
        message:
          type: string
          description: The error message.
        target:
          type: string
          readOnly: true
          description: The error target.
        details:
          type: array
          items:
            $ref: '#/components/schemas/CommunicationError'
          readOnly: true
          description: Further details about specific errors that led to this error.
        innererror:
          x-ms-client-name: innerError
          readOnly: true
          $ref: '#/components/schemas/CommunicationError'
          description: The inner error if any.
  parameters:
    ApiVersionParameter:
      in: query
      name: api-version
      description: Version of API to invoke
      required: true
      x-ms-parameter-location: client
      schema:
        type: string
  securitySchemes:
    azure_auth:
      type: oauth2
      flows:
        implicit:
          scopes:
            user_impersonation: impersonate your user account
          authorizationUrl: https://login.microsoftonline.com/common/oauth2/authorize
      description: Azure Active Directory OAuth2 Flow
x-ms-parameterized-host:
  hostTemplate: '{endpoint}'
  useSchemePrefix: false
  parameters:
  - $ref: '#/components/parameters/Endpoint'