Microsoft Azure Communication Services Browse, reserve and purchase available phone numbers API

openapi: 3.2.0
info:
  title: PhoneNumbersClient Browse, reserve and purchase available…
  description: The phone numbers client uses Azure Communication Services to purchase and manage phone numbers.
  version: '2025-06-01'
tags:
- name: Browse, reserve and purchase available phone numbers
paths:
  /availablePhoneNumbers/countries/{countryCode}/:browse:
    post:
      tags:
      - Browse, reserve and purchase available phone numbers
      summary: Browses for available phone numbers to purchase
      description: Browses for available phone numbers to purchase. The response will be a randomized list of phone numbers available to purchase matching the browsing criteria. This operation is not paginated. Since the results are randomized, repeating the same request will not guarantee the same results.
      operationId: PhoneNumbers_BrowseAvailableNumbers
      parameters:
      - $ref: '#/components/parameters/ApiVersionParameter'
      - $ref: '#/components/parameters/CountryCodeParameter'
      responses:
        '200':
          description: A randomized list of phone numbers available to purchase matching the browsing criteria.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneNumbersBrowseResult'
        default:
          description: Failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommunicationErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PhoneNumbersBrowseRequest'
        description: An object defining the criteria to browse for available phone numbers.
        required: true
  /availablePhoneNumbers/reservations:
    get:
      tags:
      - Browse, reserve and purchase available phone numbers
      summary: Lists all reservations
      description: Retrieves a paginated list of all phone number reservations. Note that the reservations will not be populated with the phone numbers associated with them.
      operationId: PhoneNumbers_ListReservations
      parameters:
      - $ref: '#/components/parameters/ApiVersionParameter'
      - $ref: '#/components/parameters/MaxPageSizeParameter'
      responses:
        '200':
          description: A collection of Phone Number Reservations, and an optional link to the next page of results.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneNumbersReservations'
        default:
          description: Failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommunicationErrorResponse'
      x-ms-pageable:
        nextLinkName: nextLink
        itemName: reservations
  /availablePhoneNumbers/reservations/{reservationId}:
    patch:
      tags:
      - Browse, reserve and purchase available phone numbers
      summary: Creates or updates a reservation by its ID
      description: Adds and removes phone numbers from the reservation with the given ID. The response will be the updated state of the reservation. Phone numbers can be reserved by including them in the payload. If a number is already in the reservation, it will be ignored. To remove a phone number, set it explicitly to null in the request payload. This operation is idempotent. If a reservation with the same ID already exists, it will be updated, otherwise a new one is created. Only reservations with 'active' status can be updated. Updating a reservation will extend the expiration time of the reservation to 15 minutes after the last change, up to a maximum of 2 hours from creation time. Partial success is possible, in which case the response will have a 207 status code.
      operationId: PhoneNumbers_CreateOrUpdateReservation
      parameters:
      - $ref: '#/components/parameters/ApiVersionParameter'
      - $ref: '#/components/parameters/ReservationIdParameter'
      - $ref: '#/components/parameters/ReservationParameter'
      responses:
        '201':
          description: Reservation successfully created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneNumbersReservation'
        '200':
          description: Reservation successfully updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneNumbersReservation'
        '207':
          description: Reservation operation partially succeeded. This can happen when the operation (create or update) is processed successfully, but it failed for at least one of the phone numbers in the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneNumbersReservation'
        default:
          description: Failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommunicationErrorResponse'
    get:
      tags:
      - Browse, reserve and purchase available phone numbers
      summary: Gets a reservation by its ID
      description: Retrieves the reservation with the given ID, including all of the phone numbers associated with it.
      operationId: PhoneNumbers_GetReservation
      parameters:
      - $ref: '#/components/parameters/ApiVersionParameter'
      - $ref: '#/components/parameters/ReservationIdParameter'
      responses:
        '200':
          description: Successfully retrieved the reservation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneNumbersReservation'
        default:
          description: Failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommunicationErrorResponse'
    delete:
      tags:
      - Browse, reserve and purchase available phone numbers
      summary: Deletes a reservation by its ID
      description: Deletes the reservation with the given ID. Any phone number in the reservation will be released and made available for others to purchase. Only reservations with 'active' status can be deleted.
      operationId: PhoneNumbers_DeleteReservation
      parameters:
      - $ref: '#/components/parameters/ApiVersionParameter'
      - $ref: '#/components/parameters/ReservationIdParameter'
      responses:
        '204':
          description: Reservation successfully deleted.
        default:
          description: Failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommunicationErrorResponse'
  /availablePhoneNumbers/reservations/{reservationId}/:purchase:
    post:
      tags:
      - Browse, reserve and purchase available phone numbers
      summary: Starts the purchase of all phone numbers in the reservation
      description: Starts a long running operation to purchase all of the phone numbers in the reservation. Purchase can only be started for active reservations that at least one phone number. If any of the phone numbers in the reservation is from a country where reselling is not permitted, do not resell agreement is required. The response will include an 'Operation-Location' header that can be used to query the status of the operation.
      operationId: PhoneNumbers_PurchaseReservation
      parameters:
      - $ref: '#/components/parameters/ApiVersionParameter'
      - $ref: '#/components/parameters/ReservationIdParameter'
      responses:
        '202':
          description: The service has accepted the request and will start processing later. It will return 'Accepted' immediately and include an 'Operation-Location' header. Client side should further query the operation status using the URL specified in 'Operation-Location' header.
          headers:
            Operation-Location:
              description: URL to query for status of the operation.
              schema:
                type: string
            operation-id:
              description: The operation id.
              schema:
                type: string
            reservation-purchase-id:
              description: The reservation purchase operation id.
              schema:
                type: string
        default:
          description: Failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommunicationErrorResponse'
      x-ms-long-running-operation: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PhoneNumbersReservationPurchaseRequest'
components:
  schemas:
    PhoneNumberCapabilities:
      description: Capabilities of a phone number.
      required:
      - calling
      - sms
      type: object
      properties:
        calling:
          description: Capability value for calling.
          enum:
          - none
          - inbound
          - outbound
          - inbound+outbound
          type: string
          x-ms-enum:
            name: PhoneNumberCapabilityType
            modelAsString: true
        sms:
          description: Capability value for SMS.
          enum:
          - none
          - inbound
          - outbound
          - inbound+outbound
          type: string
          x-ms-enum:
            name: PhoneNumberCapabilityType
            modelAsString: true
    PhoneNumbersBrowseResult:
      required:
      - phoneNumbers
      type: object
      description: The result of a phone number browse operation.
      properties:
        phoneNumbers:
          description: The phone numbers that are available for purchase.
          type: array
          items:
            $ref: '#/components/schemas/AvailablePhoneNumber'
    PhoneNumbersReservationPurchaseRequest:
      description: The phone number search purchase request.
      type: object
      properties:
        agreeToNotResell:
          description: The agreement to not resell the phone numbers. Defaults to false if not provided.
          type: boolean
    PhoneNumbersReservations:
      required:
      - reservations
      type: object
      description: Represents a list of phone numbers reservations. Note that the phone numbers from each reservation are not included.
      properties:
        reservations:
          description: Represents a list of phone numbers reservations. Note that the phone numbers from each reservation are not included.
          type: array
          items:
            $ref: '#/components/schemas/PhoneNumbersReservation'
        nextLink:
          description: Represents the URL link to the next page of phone number results.
          type: string
    PhoneNumberCost:
      description: The incurred cost for a single phone number.
      required:
      - amount
      - billingFrequency
      - currencyCode
      type: object
      properties:
        amount:
          format: double
          description: The cost amount.
          type: number
        currencyCode:
          description: The ISO 4217 currency code for the cost amount, e.g. USD.
          type: string
        billingFrequency:
          description: The frequency with which the cost gets billed.
          enum:
          - monthly
          type: string
          x-ms-enum:
            name: BillingFrequency
            modelAsString: true
    PhoneNumbersReservation:
      type: object
      description: Represents a reservation for phone numbers. A reservation is a temporary hold on phone numbers that can later be purchased. The reservation has a limited lifetime after which the phone numbers are released if not purchased. Reservations older than 1 month are automatically deleted.
      properties:
        id:
          description: The id of the reservation.
          type: string
          format: uuid
          readOnly: true
        expiresAt:
          description: The time at which the reservation will expire. If a reservation is not purchased before this time, all of the reserved phone numbers will be released and made available for others to purchase.
          type: string
          format: date-time
          readOnly: true
        phoneNumbers:
          type: object
          description: A dictionary containing the reservation phone numbers. The key is the ID of the phone number (digits only) and values are AvailablePhoneNumber objects. Not populated when retrieving PhoneNumbersReservation collections.
          additionalProperties:
            $ref: '#/components/schemas/AvailablePhoneNumber'
        status:
          type: string
          description: 'Represents the status of the reservation. Possible values include: ''active'', ''submitted'', ''completed'', ''expired''.'
          readOnly: true
          enum:
          - active
          - submitted
          - completed
          - expired
          x-ms-enum:
            name: ReservationStatus
            modelAsString: true
    PhoneNumbersBrowseRequest:
      description: The parameters for the browse operation.
      required:
      - phoneNumberType
      type: object
      properties:
        phoneNumberType:
          description: Represents the number type of the offering.
          enum:
          - geographic
          - tollFree
          - mobile
          type: string
          x-ms-enum:
            name: PhoneNumberType
            modelAsString: true
        capabilities:
          $ref: '#/components/schemas/PhoneNumberBrowseCapabilitiesRequest'
        assignmentType:
          description: Represents the assignment type of the offering. Also known as the use case.
          enum:
          - person
          - application
          type: string
          x-ms-enum:
            name: PhoneNumberAssignmentType
            modelAsString: true
        phoneNumberPrefixes:
          description: The phone number prefix to match. If specified, the search will be limited to phone numbers that start with the any of the given prefixes.
          type: array
          items:
            type: string
          example:
          - '1425'
          - '1626'
    CommunicationErrorResponse:
      description: The Communication Services error.
      type: object
      required:
      - error
      properties:
        error:
          description: The Communication Services error.
          $ref: '#/components/schemas/CommunicationError'
    AvailablePhoneNumberError:
      readOnly: true
      type: object
      description: Contains error details in case of failure when reserving, releasing or purchasing the phone number. Note that this is ignored by the service when present in requests.
      properties:
        code:
          readOnly: true
          type: string
          description: The error code indicating the reason why the operation performed on the phone number failed.
        message:
          readOnly: true
          type: string
          description: The error message describing the failure that occurred.
    AvailablePhoneNumber:
      required:
      - countryCode
      - capabilities
      - phoneNumberType
      - assignmentType
      type: object
      description: Represents a phone number available in inventory
      properties:
        id:
          description: The id of the phone number.
          type: string
          readOnly: true
        countryCode:
          description: The ISO 3166-2 country code, e.g. US.
          type: string
        phoneNumber:
          description: The phone number in E.164 format, e.g. +11234567890.
          type: string
          readOnly: true
        capabilities:
          $ref: '#/components/schemas/PhoneNumberCapabilities'
        phoneNumberType:
          description: Represents the number type of the offering.
          enum:
          - geographic
          - tollFree
          - mobile
          type: string
          x-ms-enum:
            name: PhoneNumberType
            modelAsString: true
        assignmentType:
          description: Represents the assignment type of the offering. Also known as the use case.
          enum:
          - person
          - application
          type: string
          x-ms-enum:
            name: PhoneNumberAssignmentType
            modelAsString: true
        cost:
          readOnly: true
          type: object
          description: The incurred cost for this phone number.
          allOf:
          - $ref: '#/components/schemas/PhoneNumberCost'
        status:
          readOnly: true
          description: 'Represents the status of the phone number. Possible values include: ''available'', ''reserved'', ''expired'', ''error'', ''purchased''.'
          type: string
          enum:
          - available
          - reserved
          - expired
          - error
          - purchased
          x-ms-enum:
            name: AvailablePhoneNumberStatus
            modelAsString: true
        isAgreementToNotResellRequired:
          description: Indicates if do not resell agreement is required. If true, the phone number cannot be acquired unless the customer provides explicit agreement to not resell it.
          type: boolean
          readOnly: true
        error:
          $ref: '#/components/schemas/AvailablePhoneNumberError'
    PhoneNumberBrowseCapabilitiesRequest:
      description: The minimum desired capabilities for the browse operation request.
      type: object
      properties:
        calling:
          description: Capability value for calling.
          enum:
          - none
          - inbound
          - outbound
          - inbound+outbound
          type: string
          x-ms-enum:
            name: PhoneNumberCapabilityType
            modelAsString: true
        sms:
          description: Capability value for SMS.
          enum:
          - none
          - inbound
          - outbound
          - inbound+outbound
          type: string
          x-ms-enum:
            name: PhoneNumberCapabilityType
            modelAsString: true
    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:
    ReservationParameter:
      in: body
      name: reservation
      description: A representation of the desired state of the reservation.
      required: true
      schema:
        $ref: '#/components/schemas/PhoneNumbersReservation'
      x-ms-parameter-location: method
    ReservationIdParameter:
      in: path
      name: reservationId
      description: The id of the reservation.
      required: true
      x-ms-parameter-location: method
      schema:
        type: string
        format: uuid
    CountryCodeParameter:
      in: path
      name: countryCode
      description: The ISO 3166-2 country code, e.g. US.
      required: true
      x-ms-parameter-location: method
      schema:
        type: string
    MaxPageSizeParameter:
      in: query
      name: maxPageSize
      description: An optional parameter for how many entries to return, for pagination purposes. The default value is 100.
      x-ms-parameter-location: method
      schema:
        type: integer
        format: int32
        default: 100
    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'